Doctopus
The simplest way to write beautiful documentation.
Write Markdown files in your docs directory. Run doctopus to generate a static site. Done.
You get a static HTML site that is easy to read for both humans and AI.
If you need a more complex homepage, you can write it in React instead of Markdown.
Just create an index.tsx file in the docs directory and export an App component.
Static at build time
- Static HTML with all reasonable accessibility features
- Static machine-readable pages for AI agents
- Static SVG math using familias MathJax
- Static SVG diagrams using different diagram engines
- Static syntax highlighting by a real context-aware parser
- Static search index (obviously the search widget requires client-side JavaScript)
- Static HTTP response headers for static site hosting like Cloudflare Pages
Performance
I compared Doctopus to MkDocs on the MkDocs documentation.
| Tool | Command | Mean [ms] | Std Dev [ms] | Min [ms] | Max [ms] |
|---|---|---|---|---|---|
| MkDocs | mkdocs build --clean | 706.9 | 5.7 | 697.3 | 718.3 |
| Doctopus | doctopus build | 492.4 | 5.8 | 482.0 | 514.5 |
These tools have a very different feature-set and any comparison is unfair. This should just give you a rough idea.
Most of the Doctopus generation time is spent on things that MkDocs does not do at all.
MkDocs is not even doing syntax highlighting at build time.
It bundles the syntax highlighter as JavaScript and runs it at runtime.
Not even the navigation is working properly without JavaScript on MkDocs.
All benchmarks were run on a MacBook Pro M4 Max.
Why?
I used Astro Starlight for a while and it works but was not the right fit for my needs.
The documentation software I've tried so far offered features I didn't want and lacked some I did. They offered customization in places I didn't care about, but lacked the customization I needed. And they were way too slow.
My philosophy is to write software that respects me and my users.
I wanted full static builds, no server, no client-side JavaScript for rendering static diagrams/math, image optimization by default, machine-readable pages for AI agents. I wanted a fully custom and interactive homepage, with the rest of the documentation as boring Markdown.
Finally, a reasonable build time was essential This documentation builds in under 40 ms on my laptop. This is usually less than the time Node.js takes to start up, before it can start to do actual work.
I made this program for my needs. If my needs align with yours, feel free to use it.
If you you want parts of it, it is built in a way to be consumable as a library. As a library it offers more flexibility than I surfaced in the CLI. The CLI auto-discovers everything and is made for easy use. The library is more explicit and offers more control.
Installation
Pre-compiled
curl --proto '=https' --tlsv1.3 -sSf https://doctopus.frankmayer.dev/install.sh | sh
Or download the latest release from the releases page.
From source
go install codeberg.org/tsukinoko-kun/doctopus@latest
or
git clone https://codeberg.org/tsukinoko-kun/doctopus
cd doctopus
go install .
You need to have Go and GCC installed.
On Windows, only MinGW is supported. This is because of a Rust dependency.
License and usage
This program is licensed under the Zlib license.
The source code is available on Codeberg.
You can use this program for free. The default footer contains a link to this website. You are allowed to remove it but I would appreciate it if you left it in.
Breaking changes
This program is still in an early stage. But breaking changes are unlikely and I will try my best to avoid them.
Users of Doctopus
Want to get listed here? Open an issue.