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. Here are some features:

• Pure Typst workflow

• Features inherited from Typst:

  • Simple yet expressive Typst syntax helping you focussing on your content
  • Native syntax highlighting
  • Native MathML output
  • Fast compliation
  • Native support for watch and serve
  • PDF and HTML generation from the same source ¹PDF generation is currently suspended. See https://github.com/typst/typst/issues/8309 for details.
  • HTML minification ²HTML minification is currently internal to Typst. See https://github.com/typst/typst/issues/5512 for details.
• No client side JS by default, including when using Math.
• Good SEO
• Semantic output, and
• Minimal setup

You can make a new project in Typst using Otter Docs, set it to bundle export, and Otter Docs would generate a site for you. 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 features:

• Internationalization support
• Built-in search functions

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.