Request for a theme tuned for displaying documentation

[PierreR]

Hi,

I would love a theme designed to display documentation.

I am quite interested in styx because I am using nix already and there isn't a lot of good static site generator that support asciidoc as first citizen.

Something akin https://github.com/matcornic/hugo-theme-learn or https://readthedocs.org.

(As an extra note the hugo theme does not support the toc attribute).

To be even more precise, I currently use asciidoc as a notebook and would love to separate the different topics as menu items but keeping the whole as a single source repository.

The only guideline I could find so far would go toward generating each section separately (without using styx) and use styx to aggregate all the static content afterwards. As far as I can tell, that's how the styx website works. But to be honest I found that path clumsy enough ;-)

Anyhow I would be happy if such a theme comes up in the future.

Cheers,

[ericsagnes]

A documentation theme will definitely be nice to have.

I have looked at learn and docdock, but have mixed feelings about the way content is organized.

The main issue being how table of contents / side navigation and contents are handled: table of contents is modelized using the file hierarchy, so pages need to be split accordingly and content order is managed with metadata / front matter.
For example learn pages page side menu / toc does not contains Folders or Types. It tries to redo a lot of what asciidoc is already doing, and require some extra organization work.

As we already support asciidoc, I would rather go with a solution fully compatible with it, generating the full documentation HTML including toc from the asciidoc source.
It will be required to some manipulations on the generated html such as extract the toc in a separate attribute and fix its links, but all in all feels a simpler approach.
This has the disadvantage to support only asciidoc for documentation pages, but as asciidoc is superior to markdown in that domain, I would say that it is fine. (And markdown dedicated approaches could be added afterwards)

Then, for example, it should be possible to split your notebook in per topic files like the following:

content/
├── nix.adoc 
├── haskell.adoc
├── ...
└── pages/
    └── foo.md

And have each adoc file generated as a page, with an entry in the side menu and its toc as a sub-navigation.

Does that sound like a reasonable approach?

[PierreR]

Yes ! I only care about asciidoc myself so I would be quite happy with such an approach.

Does it means that all include pages (for instance include::haskell/concepts.adoc[] in haskell.adoc) would go in the pages folder ?

I don't feel confident enough at this stage for contributing to such a theme directly but I would be more than happy to test it, learn from it and (who knows) propose some improvement if needed.

In case it helps, here is the github repository of my notebook