--- atroot: true template: slug: docs title: We rolled our own documentation site subtitle: You don't need Mintlify date: 2026-01-12 authors: - name: Akshay email: akshay@tangled.org handle: oppi.li draft: false --- 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](https://tangled.org/tangled.org/core). - 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](https://www.mintlify.com/): It is quite obvious from their homepage that Mintlify is performing an AI pivot for the sake of doing so. - [Docusaurus](https://docusaurus.io/): The generated documentation site is quite nice, but the value of pages being served as a full-blown React SPA is questionable. - [MkDocs](https://www.mkdocs.org/): Works great with JS disabled, however the table of contents needs to be maintained via `mkdocs.yml`, which can be quite tedious. - [MdBook](https://rust-lang.github.io/mdBook/index.html): 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](https://pandoc.org/) is a wonderfully customizable markup converter. It provides a "chunkedhtml" output format, which is perfect for generating documentation sites. Without any customization, [this](https://pandoc.org/demo/example33/) is the genera…