Ask HN: What are you using for public documentation these days?

   - it is easy to configure/customise 
   - looks really great out of the box
   - solid documentation
   - fast

One thing that bothers us: we have not figure a way to name the anchor that both work in Github (`<span id='aws-s3'/>`) and Docusaurus (`{#aws-s3}`), for example [2]. Any ideas?

[1] https://juicefs.com/docs/community/introduction [2] https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...

Your suggestion is better than current one, we will use that, thanks!

One thing that bothers me is that they offer a free Algolia integration for open-source projects, but they declined my application despite being open source.

So, search not working for now, need to have another look at that :-)

The two separate hamburger menus were hard to parse at first on mobile. Do your social media links really deserve higher placement than the navigation?

You could also write your own remark plugin, that does it for you, and would have the benefit of having more control over what happens on the github side if it was still standard markdown.

Some of the styling could be improved (those section headings for one!), but IMHO it produces better results than other more general-purpose manpage to HTML converters: see e.g. <https://www.htslib.org/doc/samtools.html>.

Docs are kept in separate folders for each release.

https://github.com/multiprocessio/datastation-documentation

It can generate HTML, CHM, PDF etc, all from a single source.

It is one of my favourite software tools (I am a customer and have no financial interest in it).

https://documentation.page/

It's "unfinished" because I'd need to integrate payments and do all the accounting on my side (non-trivial as an individual living in Japan), but otherwise it's worked pretty well for my own projects.

It parses your Github Repo to generate the website. You can define your docs as a single readme.md file, a folder called "documentation", or custom configuration otherwise. Some examples hosted by Documentation Page:

- https://statux.dev/: simple single-page docs and website, menu config in https://github.com/franciscop/statux/blob/master/documentati....

- https://react-test.dev/: split into multiple pages, you specify the folder and it'll automatically merge the markdown files. See config https://github.com/franciscop/react-test/blob/master/documen...

- https://crossroad.page/: has an landing page, but that is not officially supported (yet). See the configs in https://github.com/franciscop/crossroad/blob/master/document...

Also it's pretty funny that a documentation service has incomplete documentation. https://documentation.page/documentation#how-it-works

I might retake it at some point next year to officially finish/launch it, like the code is basically mostly there.

For non-TypeScript codebases, we use [Docusaurus](https://docusaurus.io/).

I believe there are also plugins which can make TypeDoc output compatible with Docusaurus.

None of our docs are public at the moment, but a good example of documentation generated by TypeDoc would be Amazon's `aws-sdk`: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index...

I did a fair amount of customization though, so I am running all this as mkdocs plugins, not directly from the materials project.

[1] https://squidfunk.github.io/mkdocs-material/ [2] https://ethereum-blockchain-developer.com

Cheers for this :)

The free version is really nice but also very happy to pay for the 'insiders' version via GitHub donations.

I do wish it supported running code snippets, but I think that can be done with some scripts and including things. (On the list, not done yet.)

The downside: quite a lot of work to create something from scratch.

The upside: I have created a playground-type API, where all options, methods & events can be tried out directly from the docs. They interact with the data grid.

https://www.datagridxl.com/api/options

Our challenge right now with the docs is to get a fantastic code snippet runner there. But that's beyond the scope of your regular documentation management tool, I suppose. VuePress will make it easy for us to integrate our solution.

[1] https://vuepress.vuejs.org/

[2] https://handsontable.com/docs/

[0]: https://www.archbee.io/ [1]: https://readme.com/

It's zero effort which is important for a small team like ours. Allows us to focus on the content as opposed to bikeshedding design.

Overall I'm happy with the look and feel of things and the support is typically good.

That being said, they recently shipped changes that essentially made the docs site impossibly slow for a few days. They've been working on fixing that and it's better, but not as snappy as before. I also preferred the previous look (it's very similar but the new one is a bit more clunky imo).

We do have a lot of long code examples (YAML reference docs) which I think may contribute to the "sluggishness".

But overall I'd recommend if you want to minimise effort and maintenance. In any case it's easy to give it a spin and see if it works for you.

Although we're using Asciidoctor (syntax / markup language) with Antora (tooling) ourselves, including with a Chinese translation. It's similar to the Fedora documentation:

https://docs.fedoraproject.org/ur_PK/docs/ (Urdu? Most translations are very incomplete; it's just volunteers.)

The 'docs' theme is intended as a quick way to produce a documentation website based on Next, which you can obviously customise further with your own components if needed.

Pretty satisfied with the productivity gain and the API docs generation from our OpenAPI file.

I just learned that their API would allow us to programmatically update the guide section as well, so we'll probably move the guides to a public github as well for contributions.

[1] https://docs.flagsmith.com/

https://github.com/rust-lang/mdBook

I have also noticed that in VS Code a comment immediately preceding a type or interface declaration written in mark down format becomes formatted markdown in the tooltip where that type is used.