Doctopus
Doctopus is a documentation generator.
It turns a docs directory into a fully static website: HTML pages, navigation, syntax-highlighted code, math, diagrams, media, metadata, search, favicons, response headers, and optional versioned documentation.
The goal is not to be the most customizable documentation tool. The goal is to produce a complete static site quickly, with a build that is easy to run today and still easy to run years from now.
doctopus build
The Problem
Many tools describe their output as static.
In practice, that often means only part of the page is static. The remaining work is moved somewhere else.
Some work moves into the build environment through Node.js, Python packages, plugins, themes, or version-specific toolchains. Some work moves into the user's browser through JavaScript that finishes rendering, highlighting, layout, navigation, or other page behavior at runtime.
That approach is flexible, but it has costs. The build becomes harder to reproduce. CI needs more setup. Old projects become harder to rebuild. Users download more JavaScript. Pages can shift while the browser finishes the work. Search engines and non-browser tools have to understand a less complete document.
Doctopus takes the opposite approach.
What Doctopus Does Differently
Doctopus builds as much as possible into the output itself.
Code is parsed and highlighting is generated at build time. Math and diagrams become static SVG. Navigation and metadata are written into the HTML. The result is already a complete document when it reaches the browser.
This gives the generated site a few practical advantages:
- fast loading
- no layout shifts from late rendering
- little runtime JavaScript
- readable HTML
- good SEO
- simple static hosting
- fewer moving parts
Search is the exception. Search is interactive by nature, so the search widget uses client-side JavaScript. The search index itself is generated during the build.
Built In, Not Assembled From Plugins
Doctopus does not rely on plugins. It does not have plugins and probably never will.
It already includes the parts I consider essential for technical documentation.
That is the main difference. Other tools can often be configured to do similar things, but the final setup is usually assembled from a tool, a theme, plugins, package managers, and runtime scripts.
Doctopus is one executable with these capabilities built in.
The Tradeoff
Doctopus is less customizable than larger systems.
What it allows you to customize:
- Basics like URL, title, description, and favicon of course.
- Theme variables. These are color variables, used by the theme.
- Custom CSS. You can override the default stylesheet. I would not recommend this but it is possible.
- Homepage in React. You can use a Markdown homepage
index.mdor a React homepageindex.tsx(no Node.js required). - Pre-build and post-build hooks. If you want to generate a page, modify some output, etc. you can do that.
If you want your documentation to be as complex as the project it documents, Doctopus is probably not the right tool. Use something like Starlight. If you want a focused documentation generator that produces complete static output with very little machinery, Doctopus may fit well.
Performance
Doctopus does more at build time than any other documentation tool I could find, but it is still faster than any of them.
As a rough comparison, I built the MkDocs documentation with MkDocs and with Doctopus on my MacBook Pro M4 Max:
| Tool | Command | Mean |
|---|---|---|
| MkDocs | mkdocs build --clean | 706.9 ms |
| Doctopus | doctopus build | 492.4 ms |
This is not a perfect benchmark. The tools do different work. The point is narrower: Doctopus can build a more complete static result while still keeping build times low.
This site you are currently reading usually builds in under 40 ms on my MacBook.
Why I Built It
I built Doctopus because I wanted a documentation tool that did the static part seriously, while not overshadowing the actual thing I want to document in build complexity.
The other tools I tried were working. There is nothing that Doctopus does, that you cannot do with these other tools. But this results in a lot of configuration files, custom themes or plugins and slow builds.
Doctopus is a personal project, not a SaaS product. It is built by an engineer trying to close a specific gap. The scope is deliberately small, but the implementation is meant to be solid.
Installation
Prebuilt Binary
curl --proto '=https' --tlsv1.3 -sSf https://doctopus.frankmayer.dev/install.sh | sh
You can also download a release from the Codeberg releases page and install it yourself. The script is not doing anything other than that.
From Source
go install codeberg.org/tsukinoko-kun/doctopus@latest
Or:
git clone ssh://[email protected]/tsukinoko-kun/doctopus.git
cd doctopus
go install .
Building from source requires Go and GCC.
On Windows, only MinGW is supported because of a Rust dependency. The reason is that I pre-compiled this dependency so that Rust is not required to build Doctopus.
Source and License
Doctopus is licensed under the Zlib license.
The source code is available on Codeberg.
You can use Doctopus for free. The default footer links back to this website. You are allowed to remove (or modify) it, but I appreciate it if you leave it in.
Stability
Doctopus is still early software.
Breaking changes are possible, but I try to avoid them. The goal is not churn. The goal is a small tool that stays easy to build, easy to run, and easy to understand.
Users of Doctopus
Want to be listed here or have any issues or questions? Open an issue on Codeberg.
If you are not on Codeberg, you can write me an email.