We rolled our own documentation site

Summary

We recently organized our documentation and put it up on https://docs.tangled.org, using just pandoc. For several reasons, using pandoc to roll your own static sites is more than sufficient for small projects. requirements Lives in our monorepo. No JS: a collection of pages containing just text should not require JS to view! Searchability: in practice, documentation engines that come bundled with a search-engine have always been lack lustre. I tend to Ctrl+F or use an actual search engine in most scenarios. Low complexity: building, testing, deploying should be easy. Easy to style evaluating the ecosystem I took the time to evaluate several documentation engine solutions: Mintlify: It is quite obvious from their homepage that mintlify is performing an AI pivot for the sake of doing so. Docusaurus: The generated documentation site is quite nice, but the value of pages being served as a full-blown React SPA is questionable. MkDocs: Works great with JS disabled, however the table of contents needs to be maintained via mkdocs.yml, which can be quite tedious. MdBook: As above, you need a SUMMARY.md file to control the table-of-contents. MkDocs and MdBook are still on my radar however, in case we need a bigger feature set. using pandoc pandoc is a wonderfully customizable markup converter. It provides a “chunkedhtml” output format, which is perfect for generating documentation sites. Without any customization, this is the generated output, for this markdown file input. You get an autogenerated TOC based on the document layout Each section is turned into a page of its own Massaging pandoc to work for us was quite straightforward: I first combined all our individual markdown files into one big DOCS.md file. Modified the default template to put the TOC on every page, to form a “sidebar”, see docs/template.html Inserted tailwind prose classes where necessary, such that markdown content is rendered the same way between tangled.org and docs.tangled.org Generating the docs is do...