**We Rolled Our Own Documentation Site**
In an effort to streamline our documentation process, we recently set up our very own documentation site at [https://docs.tangled.org](https://docs.tangled.org) using the versatile tool **pandoc**. As it turns out, using pandoc to create a static website is more than sufficient for small projects like ours.
**Evaluating Documentation Engine Solutions**
Before settling on pandoc, we evaluated several other documentation engine solutions, including **MkDocs** and **MdBook**. While these tools are certainly capable, we found that pandoc's customizability and ease of use made it the perfect choice for our needs. We've left MkDocs and MdBook on our radar in case we need to upgrade to a more feature-rich solution in the future.
**The Power of Pandoc**
Pandoc is a markup converter that offers a wide range of output formats, including the "chunkedhtml" format, which is perfect for generating documentation sites. With minimal customization, pandoc can produce high-quality documentation with ease. We were able to generate our documentation site with just one command:
```bash pandoc --from markdown --to chunkedhtml input.md -o output.html ```
**Customizing the Documentation Site**
While pandoc's output is excellent on its own, we wanted to add a few extra features to make our documentation site more user-friendly. We needed to collapse the "sidebar" style table-of-contents (TOC) on mobile displays, which proved to be a bit of a challenge.
Most documentation engines require JavaScript to achieve this effect, but pandoc can handle it with ease. We used CSS and HTML to create a collapsible TOC that works seamlessly across devices.
**Search Functionality**
We also wanted to add search functionality to our documentation site, but after evaluating various options, we decided to keep things simple. Instead of implementing a native search engine, we took inspiration from the search bar at **htmx.org**, which simply redirects users to Google. This approach has proven to be effective and easy to implement.
For larger projects, a native search engine may be necessary, but for our small documentation site, this solution works perfectly.
**Exporting Docs in Single-Page Format**
To make searching through the entire site even easier, we exported our documentation in single-page format using pandoc. This approach has several benefits, including:
* **Trivial search**: With all content on a single page, users can quickly find what they need by searching with their browser's built-in search function (Ctrl+F). * **Simplified navigation**: A single-page format eliminates the need for complex navigation menus, making it easier for users to find what they're looking for.
**Building and Deploying the Documentation Site**
As part of our infrastructure, we use **nix** and **colmena** to build and deploy all Tangled services. Creating a nix derivation to build our documentation site was a breeze with the `runCommandLocal` helper:
```bash
{ pkgs ? import
We then serve the site using **nginx** on our NixOS machine.
**Updating the Documentation Site**
To update the documentation site, we use the following workflow:
1. We bump the `tangled` flake input and rebuild `tangled-pkgs.docs`. 2. The changes are applied to the machine serving the site using **colmena**.
**The Benefits of Going Homegrown**
One of the main advantages of creating our own documentation site is that we have full control over its design and layout. This has allowed us to style the documentation site to match our main site seamlessly.
However, there are still a few discrepancies between pandoc's markdown rendering and **goldmark**'s markdown rendering (which is what we use in Tangled). In the future, we may choose to roll out our own Static Site Generator (SSG), codenamed "TigerStyle".