4 ms·
Ask HN: What do people use for documentation sites these days?
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?
- wizwit999 5y agoI've found Docusaurus quite nice and well maintained. Ours are https://apptrail.com/docs https://apptrail.com/docs as an example but there's a lot of open source projects and companies using it.
- brundolf 5y agoDocusaurus looks great, I'll probably go with that. Thanks
- jka 5y agoIf & when relevant: from looking into self-hosted search options to accompany docusaurus, https://github.com/cmfcmf/docusaurus-search-local 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).
- brundolf 5y agoThanks, 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
- thomascountz 5y agohttps://pmarsceill.github.io/just-the-docs/ 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!
- tdido 5y agoI use https://www.mkdocs.org/ https://www.mkdocs.org/, which is markdown-based. It's simple to get started and customizable enough if needed.
- acemarke 5y agoWe use Docusaurus for the Redux org doc sites like https://redux.js.org https://redux.js.org , and love it: https://docusaurus.io/ https://docusaurus.io/
- frogperson 5y agohugo and docusaurus are both pretty nice.
- karmakaze 5y agoI sometimes just edit .md files in a github repo, often from the github UI.
- verdverm 5y agoI 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.
- davidandgoliath 5y agoMkdocs.
- webmaven 5y agoI usually use Read the Docs: https://readthedocs.org/ https://readthedocs.org/
- JoeMayoBot 5y agoOn 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.
- prirun 5y agoI switched from Google Sites to https://antora.org/ https://antora.org/ for https://hashbackup.com 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.
- flurly 5y agoI used docusaurus for https://docs.graphjson.com/ 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!
- slorber 5y agoI'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
- stonecharioteer 5y agoSphinx 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.