Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enable organizing of subject nav by (definable) topic type #77

Open
capsulecorplab opened this issue Aug 28, 2021 · 2 comments
Open

Enable organizing of subject nav by (definable) topic type #77

capsulecorplab opened this issue Aug 28, 2021 · 2 comments

Comments

@capsulecorplab
Copy link
Contributor

The documentation system is a means of organizing user-facing documentation into four categories (tutorials, how-to guides, explanations, & references)

@briandominick
Copy link
Contributor

Oh I like this one. I'm going to modify it a little bit and put it right in the queue, probably for 0.4.0.

@briandominick briandominick changed the title organize navigation bar as per the documentation system Enable organizing of subject nav by (definable) topic type Aug 28, 2021
@briandominick
Copy link
Contributor

I intend to bake a few sub-features into this one.

First, the system should be user-definable. I love the idea of "The Documentation System" (which i always thought was called Diátaxis but I guess it's the same thing), but I'm not sure it's optimal in all cases. So really we want to make this customizable rather than impose a system, but I'll create default templates for Diátaxis, DITA-style, and the one I'm developing for my broader framework, which is a mix of both.

Also, I want to make it optional to let the user re-sort the menu either by topic type (this approach) or by some other order you can establish in your manifest file. This will just use JavaScript to swap the navs.

Topics will need their type defined somewhere, but we can also bake it into the filename. Say if a filename ends in _t.adoc or _r.adoc, etc, it will indicate a type (tutorial, reference, etc).

The other nice thing is we don't just have to organize the topics this way, we can give them different layouts depending on type, if that is hepful. Tutorials and how-tos often need more of the page for code/example listings, but references are often quite narrow and leave a wide margin.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants