3 min read
|
Saved February 14, 2026
|
Copied!
Do you care about this?
This article explains how to use Pandoc to build a simple, static documentation site without JavaScript. The author discusses their requirements, evaluates other documentation engines, and details their approach to styling, search functionality, and deployment using Nix and Colmena.
If you do, here's more
The team behind Tangled organized their documentation using pandoc, focusing on simplicity and efficiency for small projects. Their requirements included a monorepo structure, no reliance on JavaScript for text-heavy pages, effective searchability, low complexity in building and deploying, and ease of styling. They evaluated several documentation engines, finding that many, like Mintlify and Docusaurus, either overcomplicated the process or depended on JavaScript. They found MkDocs and MdBook appealing but noted the tediousness of maintaining table of contents files.
Using pandoc allowed them to generate a clean documentation site with a chunked HTML format, automatically creating a table of contents and individual pages for each section. They customized the default template to include the TOC on every page and styled the markdown content to match their main site. For mobile users, they implemented a collapsible sidebar TOC without JavaScript, using techniques like the `<details>` tag and a popover API for usability. While they currently lack a native search functionality, they repurposed their search bar to redirect to Google, enabling users to search the documentation effectively.
Deployment is handled through Nix and Colmena, simplifying the build and update process. The documentation site is served via Nginx, ensuring smooth access. Despite some discrepancies between pandoc and the markdown rendering used in Tangled, the homegrown solution allows for greater flexibility in design and functionality. They remain open to developing a custom static site generator if their needs expand further.
Questions about this article
No questions yet.