Introduction

Welcome to the documentation for Otter Docs 0.1.0.

Writing documentation is a lame task. It is even more boring and frustrating when you have to setup toolchains and environments and debug for hours to make sure that they build correctly, only to find that the current tools cannot plot your diagrams, or the PDF generation is missing fonts and takes hours to build. So here’s Otter Docs. A simple tool that has a single requirement: Typst.

Typst is good at generating PDFs. It also has experimental support for HTML files. Since #7964 Typst can export multiple files for a single project, which makes it ideal for stuff like documentation sites.

Otter Docs uses the bundle target. You can make a new project in Typst, set it to bundle export, and it would generate a site for you. It’s only a typst template, and you don’t need to worry about setting up the toolchain – Typst is the only tool required.

An Unfinished Project

Otter Docs is a decent choice for organizing long, comprehensive documentation. But just like Typst, Otter Docs is an unfinished project, and is (currently) not a serious tool. Specifically, it’s missing these stuff:

However, if you want pure Typst documentation, ease of use, and/or MathML formulae, you might want to give it a try. If you want stability and extremely easy syntax, then maybe you should consider mdBook. If you have any issues, please feel free to open a ticket on GitHub. If you would like to contribute, please open a pull request.

Installation

Because Otter Docs is a pure Typst framework, you do not need to install other tools. No Python, no shell scripts, only Typst. However, there are some caveats. Otter Docs is not currently available on the Typst Universe, and it requires a very specific version of Typst. You would, unfortunately, have to build the compiler yourself. If you are a Nix user, you can use the flake.nix file in the repository to setup the environment.

Once Typst 0.15 releases and Otter Docs makes its way to the Universe, the installation process should just be a simple one liner like #import "@preview/otter-docs:0.1.0": *.

Licensing

The source and the documentation are available under Apache License v2.0.