Ask HN: What do people use for documentation sites these days? | Hacker News Reader

Ask HN: What do people use for documentation sites these days?

20 pointsbrundolf17 comments

I have an upcoming need to document a large project (reference manual, tutorials, etc). I'm a web dev but I don't want to spend a ton of time making something custom. I assume there are popular, nice-looking static site generators out there for this type of thing. Should be free and self-hostable, and any special features for embedding code and such would be cool too. I don't need a CMS, in fact Markdown would be preferred.

Any recommendations?

View on HN

I use https://www.mkdocs.org/, which is markdown-based. It's simple to get started and customizable enough if needed.

I've found Docusaurus quite nice and well maintained. Ours are https://apptrail.com/docs as an example but there's a lot of open source projects and companies using it.

Docusaurus looks great, I'll probably go with that. Thanks

If & when relevant: from looking into self-hosted search options to accompany docusaurus, https://github.com/cmfcmf/docusaurus-search-local looks like one potential candidate (search is performed locally; so your mileage may vary based on the document set size).

Thanks, but I was planning to just put the site on a CDN and do local-search within the user's browser. It'll be a significant site, but should be smaller than average in terms of documentation sites as a category

I used docusaurus for https://docs.graphjson.com/ and it's been super great. Everything is in markdown. The file system mimics the website paths. All SEO/Meta tags are just taken care of automagically. Highly recommend!

I switched from Google Sites to https://antora.org/ for https://hashbackup.com

Antora is a little hard to get started because it invents some new concepts, like "component version", but I thought the out-of-the-box formatting was nice. I did spend a little time tweaking things after the site was converted, but not much. Antora is based on AsciiDoc, and the same guy did both.

The guy who wrote it, Dan, is on a Zulip forum and is great about offering tips for things you want to customize. I host on a $5/mo Linode with Caddy.

We use Docusaurus for the Redux org doc sites like https://redux.js.org , and love it:

https://docusaurus.io/

On one project, I use *.md files. Benefits include easy readability on GitHub (or other site that renders Markdown) and I treat documentation the same way as code and it goes through PR. Another way I do documentation is via GitHub pages, where I can give it a URL and it works like a normal website.

I'm the Docusaurus maintainer, let me know if you have questions

I think Docusaurus looks like a good fit for you.

If your project is very large, we are not the fastest SSG on terms on build times and definitively want to improve with modern Rust/Go tooling for bundling

https://pmarsceill.github.io/just-the-docs/

Especially if you're already familiar with Jekyll. Bonus points for being able to deploy on GitHub Pages!

I currently use Hugo, but am planning a switch to VuePress based on the VT theme (first on the awesome-vuepress themes section iirc). There are so many cool and helpful things with a real frontend framework.

Sphinx does everything and more. It's really powerful and it also has myriad extensions you can use. Plus RestructuredText is so much more powerful than Markdown.

I usually use Read the Docs: https://readthedocs.org/

hugo and docusaurus are both pretty nice.

I sometimes just edit .md files in a github repo, often from the github UI.

Mkdocs.

Reply on news.ycombinator.com