Tutorial

Otter Docs uses Typst. If you are not familiar with Typst, you can first take a look at Typst’s official tutorial for info on how to write Typst.

Setting Up

If you’ve used a tool like Shiroa or mdBook, you might be familiar with book.typ or summary.md. Both files contain metadata and instructions on how to organize the book. In Otter Docs, all of that is concentrated to a single entrypoint – the book function:

// Always remember to import the package
// NOTICE: OTTER DOCS IS NOT PUBLISHED TO THE TYPST UNIVERSE YET
// THIS LINE WOULD NOT WORK
#import "@preview/otter-docs:0.1.0": *

#book(
  // The routing root. Useful when you are deploying to a folder
  // under your root (e.g. when deployed to GitHub Pages)
  root: "otter-docs",
  // Your document's contents
  tree: (
    // You can add arbitrary content. The content would be displayed
    // in the summary, but would not generate html pages.
    [= Introduction],
    // This would create otter-docs/index.html. The content of the
    // chapter would be from `doc/intro.typ`
    chapter("index", content: include "doc/intro.typ"),
    // This would create otter-docs/doc/tutorial.html. In this case,
    // the content of the chapter is not explicitly stated, so it
    // look into ./doc/tutorial.typ in the current workspace.
    chapter("doc/tutorial"),
    // you can add more chapters here.
  )
)

Building with the Command Line

You can then compile using the following arguments in your command line. Remember to replace <input-file> with your actual filename

$ typst compile --features bundle,html <input-file> --format bundle ./dist

This would create the documentation in the ./dist folder. Additionally, you can change compile to watch and add the --open flag at the end to preview your document in real time. You can edit your .typ source files, and any edits would be reflected immediately.

Building with the Web App

(The typst.app web app currently does not support the bundle target and MathML exports).

Authoring

Each chapter should start with a title. The title of the page would also be displayed in the summary. Do not start your document with a level 1 heading that looks like this: = Heading. Instead, write this:

#title[My amazing document]

= Heading 1

Over seas from coast to coast

= Heading 2

To find a place I love the most

The rest of your document is just normal Typst content. You could apply show rules or use functions, just like writing a normal Typst document.

Contexual Output

You can write different content for different targets, for example, embedding a link to a page via iframe in the HTML target.

#context if target() == "html" {
  // target IS HTML. Write some HTML specific stuff
} else {
  // target IS NOT HTML. It is instead "paged", which is for PDF, PNG and SVG.
  // Write some PDF specific stuff
}

You are currently looking at the HTML target. The default theme “New Hamber” is inspired by Documenter.jl’s “Documenter” theme, which is based on sphinx’s sphinx_rtd_theme. You can also take a look at the PDF document.