HN Explorer

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

174 points by vital101 ↗ HN
On a new side project I'm working on I need to have a fair amount of documentation for usage, implementation, options, etc. In the past I've used https://docsify.js.org hosted on Vercel, but I was curious if there is anything else out there people like. Looking for free or paid options. So long has I can host on a subdomain I'm indifferent.

Thanks!

110 comments

[ 2.0 ms ] story [ 185 ms ] thread
austincheney
I am frequently working on ways to document inline with the code using comments and then extract those comments during the build process to keep documentation up to date automatically. The comments are formatted as mark down so that they may be converted from code comments to stand alone mark down documents.

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.

stichers
Basic markdown and Sphinx to build into HTML, publishing via github pages. It's an open source project so putting the docs alongside the code just makes sense. Although Sphinx isn't great for my money, it gets the job done.
acidburnNSA
I have grown to absolutely love Sphinx. The plugins are wonderful, including Sphinx gallery, jupyter integration, and Sphinx-needs for requirements management.
stichers
I think it grows on you. There's a way to work with it and if you settle on that, it makes it easier than fighting against the prevailing tide. I find I spend a lot of time looking up opaque build errors but that is partly because the contributing authors aren't all that familiar with it, so their markdown is less than 'pure'
ak217
I use this combination too, and I love it. Sphinx has great hackability and support, while github pages is free and very reliable. Here is a script that I use to publish to github pages, assuming the sphinx config is under "docs":

     sphinx-build docs docs/html
     git branch -D gh-pages || true
     git checkout -B gh-pages-stage
     touch docs/html/.nojekyll
     git add --force docs/html
     git commit -m "Docs"
     git push --force origin $(git subtree split --prefix docs/html --branch gh-pages):refs/heads/gh-pages
     git checkout -
dabeeeenster
We [1] moved from mkdocs to docusaurus v2 and couldnt be happier. Very active project with a great community, and enough flexibility and config overrides when we need it.

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

tomw1808
I'm using mkdocs with the material plugins [1]. I'm running it mainly for a Blockchain Education site for my labs from my course, which seems to be fine [2].

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

evolve2k
Oh wow this looks great! Simple conversion of markdown into an opinionated simple to use really nice looking doc site.!

Cheers for this :)

sixhobbits
+1000 for the "Material for MkDocs" project by squidfunk - we (Ritza.co) do documentation for various companies and we've strongly encouraged them to all switch to this since we found it. Fast, beautiful, simple.

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

squidfunk
Thanks for your continued support!
4kelly
+1 for Material MkDocs. It’s beautiful and functional by default so I can just focus on documenting.
twalla
Another happy user of mkdocs, also really like gitbook. If I had to choose something for people who didn't like git/plaintext and wanted richer embeds, I think I'd suggest Notion.
tedyoung
Another +1 from me for mkdocs and mkdocs-material (and I'm also a supporter of squidfunk). I use it for lab exercises[1] as part of my online courses (deployed onto Netlify). It just works and looks good.

[1] https://moretestable.com

perfopt
Is there anything that supports languages other than English - specifically Indian languages. I am writing documentation (book) to be distributed online. I presently use mdbook but markdown does not support anything other than English.
Symbiote
What do you mean by Markdown not supporting other languages? I don't see how it wouldn't support other languages.

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.)

woudsma
As others in this thread have mentioned, Docusaurus is really good. It was very easy to add search with Algolia and meta tags for SEO as well.
franciscop
I have an unfinished side project called Documentation Page:

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...

djrockstar1
The examples look really elegant and polished. I could definitely see myself using something like this. It's times like these I wish HN had a save comment button.

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

ryannevius
If you click on the timestamp for the comment, you'll be presented with an option to "favorite" the comment.
franciscop
Thanks! It's unfinished and on-hold for 3rd parties so it doesn't have all docs :)

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

krish888
Stoplight.io it has support for git, CI integration
eysi
We use GitBook at Garden (docs.garden.io).

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.

navaneethpk
We are using Docusaurus (https://docusaurus.io/ ).

   - it is easy to configure/customise 
   - looks really great out of the box
   - solid documentation
   - fast
In our case, we just had to change the colors and font. Here is our Docusaurus code if that's helpful: https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/
newaccount74
Your docs even support dark mode! Did that come out of the box or did you add that?
navaneethpk
It comes out of the box. We are now trying to figure out how to switch screenshots based on the light/dark mode. The screenshots taken from light mode of ToolJet looks odd in Docusaurus' dark mode.
dsmmcken
You could build your own react image wrapper then use that component in the mdx and pass in two images, then display the appropriate one based on the current theme provider. Docusaurus makes using inline react components easy.

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.

navaneethpk
Thanks, I will try creating a custom react component for handling the modes.
lelandfe
> live documentation: https://docs.tooljet.io

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?

navaneethpk
You are right, placing the navigation on the sidebar is more useful than the links to GitHub and Slack.
dsmmcken
Update to a more recent version, they re-worked the nav to be one menu on mobile.
navaneethpk
Your comment was super helpful. I just tried upgrading to 2.0.0-beta.9. The menu now looks great on mobile. The upgrade is causing some other issues, will fix those and deploy the docs. Thanks!
navaneethpk
That was a very low-hanging fruit. Could fix and deploy it in a few minutes. There are few other improvements too related to navigation in the latest Docusaurus. Deployed here: https://docs.tooljet.com
stavros
Oh huh, I completely missed the second hamburger button and was perplexed as to why their documentation only had three links to other sites.
daviesliu
Docusaurus is great! We migrated from Sphinx to Docusaurus[1] recently, the navigation is much better than before.

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...

navaneethpk
Haven't tried this but will it work on both GitHub and Docusaurus if the section "S3" is renamed as "Amazon S3" and then removing the "{#aws-s3}" part?
daviesliu
Yes, we can use `#amazon-s3` as the anchor, then the name could be long, for example, `#digitalocean-spaces-object-storage`), and it will not work in Chinese.

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

dsmmcken
Not a great solution, but you could create the links github style, then write a remark/rehype plugin that transforms them to Docusaurus style at build time. I would probably just live with it though.
kaycebasques
What was your motivation(s) for migrating away from Sphinx?
shafyy
I'm also using Docusaurus for Fugu (https://docs.fugu.lol).

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 :-)

Edit: I just got an email from Algolia DocSearch saying that my documentation qualifies after all :-) If someone from that team read my comment and send the email, thanks! If not, it's a big coincidence, also good!

stavros
It doesn't support search unless you rely on (pay for) Algolia? Wow, instant pass from me.
shafyy
You can add your own search plugin or use another provider like Typesense. They just offer an optional free Algolia service for open-source projects on top. You can read more here: https://docusaurus.io/docs/search
stavros
Ah phew, thanks. The site made it sound like they only supported Algolia.
dsmmcken
We also use Docusaurus. It has good defaults. If you are familiar with react, mdx (markdown + jsx) allows you to easily create and embed interactive react components.

It's technically still in beta with frequent updates, and the occasional breaking change.

For our site (https://deephaven.io/core/docs/), what I liked was the ease of adding your own plugins. We made a plugin that extracts all our code examples, and automatically tests them against new versions to notify us if any examples break or become stale.

gompertz
Sort of curious, is there key differences between Docusauras and Hugo that would make it worth switching??
akajla
+1 for Docusaurus. We're using it at Warrant (https://docs.warrant.dev/). In addition to what folks have already mentioned, it has good blogging support as well (markdown, post tags, SEO/social tags etc). Makes it much easier to manage both docs + blog from the same system.
fenesiistvan
MS Word converted with some tools to html, chm, pdf.
andix
Markdown in Git, Gitlab or GitHub. KISS.
oftenwrong
This is my preferred option as well. Both GitLab and GitHub turn your markdown (and some other formats) files into static pages. They both have web-based editing support, so it is not necessary for a user to know anything about git to contribute. Both can automatically generate a table of contents for a page. And it gives you better versioning than any wiki system.
warpech
We (Handsontable) now use VuePress[1] for our docs[2] and we are very happy with it. The best feature for us is the ease of customization.

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/

royjacobs
I can vouch for VuePress as well. It's fairly straightforward to set up, and extremely easy to deploy. I've used it to not only write the docs for my 6502 assembler, MOS[1], but I took advantage of the fact that VuePress could generate a very simple front page as well.

[1] https://mos.datatra.sh

superzamp
We're using readme.com for https://docs.numary.com/

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.

Symbiote
Antora, which uses Asciidoctor (rather than Markdown).

The obvious example is the Antora and Asciidoctor documentation:

https://docs.antora.org/antora/2.3/

https://docs.asciidoctor.org/asciidoc/latest/

davidwf
Really really love Antora. I've been pushing hard for it for internal docs -- one very nice attribute is that it can collate docs from multiple Git repos. This way, you can have documentation close to the code, like I want as a developer, while having a single "documentation site" like most management and non-technical users want.
parkersweb
I've not used it yet - but planning to give Nextra (https://nextra.vercel.app/) a go next time around.

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.

Joe8Bit
If you're looking for a SaaS solution, I can really recommend Archbee[0]. We've moved to it from ReadMe[1] recently, due to constraints in ReadMe's product and the challenges scaling it commercially in our model.

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

kaycebasques
What ReadMe constraints did you run into? I don't work for them, I'm just a technical writer who has to use it from time to time and wants to be aware of footguns.
Joe8Bit
The big challenges were things that were inherent to how usage scales in their platform.

As one example, they see a 'project' as one single set of cohesive documentation and they've built a UX/UI to facilitate that. This is perfectly fair but it means you need multiple projects for multiple documentation projects. In simple terms, everything in a project is intended to be 'one thing'.

Again, this might be fine but projects are so distinct and separated that it makes them really hard to maintain at scale (lots of repetition, no setting or customization sharing) and frankly, if you need the full customisation options you need to $400 a month for _each_ project.

This is a pretty unique to our model, so it's not really a criticism of readme, but it's the reason we've left. Archbee has some (not all) of the same limitations, but they don't charge us $400 a month for each project!