Tutorial

Haita 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.

Writing Your First Document

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 Haita, all of that is concentrated to a single entrypoint – the book function. To get started, create a file named dist.typ that contains the following:

#!/usr/bin/env -S typst compile --features bundle,html --format bundle
// The line above compiles the documentation to an HTML bundle.
// Additionally, you can watch the file using this command:
// ```
// typst watch --features bundle,html --format bundle main.typ
// ```
// You can also build and watch the PDF using the follow commands:
// ```
// typst compile --features bundle,html --format pdf main.typ
// typst watch --features bundle,html --format pdf main.typ
// ```
#import "@preview/haita:0.3.0": * // Always import the package!
#book(
  // Where the site will be deployed. Optional: it is only used for the
  // SEO metadata, everything inside the site is linked relatively.
  // base-url: "https://username.github.io/haita",

  // This sets your html renderer. You can customize the HTML renderer
  // using `html-renderer.with(...)`, or write your own!
  html-renderer: new-hamber.html-renderer,
  // Your document's contents
  tree: (
    // You can add arbitrary content. The content will be displayed
    // in the summary, but will not generate html pages.
    [= Welcome!],
    // This will create index.html. The content of the
    // chapter will be from `index.typ`
    chapter("index", content: include "index.typ"),
    // This will create doc/tutorial.html. In this case,
    // the content of the chapter is not explicitly stated, so it
    // looks into ./doc/tutorial.typ in the current workspace.
    chapter(
      "doc/tutorial",
      content: include "tutorial.typ",
      // you can generate chapters procedurally
      children: range(1, 6).map(num => chapter("doc/" + str(num), content: [
        #title[Chapter #num]
        This page is generated procedurally!
      ])),
    ),
    // You can add dividers, which will separate content in the summary.
    divider(),
    // Alternatively, if you would like to directly include the content
    // without creating a new file, you can write it like this:
    chapter("my-page", content: [
      #title[My Page]
      = Heading 1
      = Heading 2
      foo bar baz
    ]),
    // you can also add arbitrary content
    [Made with Haita.],
    // you can add more chapters afterwards.
  ),
)

Each chapter should start with a title. The title of the page will 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
Overseas 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.

Developing (Typst Web App)

The typst.app web app currently does not support the bundle target and MathML exports. Bundle export would not work in the Web App.

https://typst.app is an online Typst editor developed by the Typst team.

Developing (Local machine)

Bundle (HTML) Export

Open a terminal on your device. In the terminal, type the following command, then press return:

typst compile --features bundle,html --format bundle dist.typ

This will generate a folder dist/ inside the same folder where you put your dist.typ file. The content inside dist/ is your document. You can see more available options by executing typst help.

The typst compile command only generates dist/ once. Any subsequent edits will not appear inside dist/. Use the following command to let Typst monitor your changes:

typst watch --features bundle,html --format bundle dist.typ

This will also generate a folder dist/ alongside dist.typ, but this time there is some extra information:

watching ./dist.typ
writing to ./dist
serving at http://127.0.0.1:3000         <-- notice this line!

[HH:MM:SS] compiled with warnings in <some-time>

warning: bundle export is experimental
 = hint: its behaviour may change at any time
 = hint: do not rely on this feature for production use cases

This tells you that Typst is actively monitoring your files, and any changes you make to the files will let Typst recompile the project. This line serving at http://127.0.0.1:3000 (3000 might be a different number) tells you that Typst has opened a local development server that this specific address. You can copy http://127.0.0.1:3000, open a browser, and paste that line in the address bar.

You will see your document’s index page in your browser.

PDF Export

You can export your entire document as a PDF using the following command:

typst compile --features bundle,html --format pdf dist.typ

This would generate a file named dist.pdf which you can open in your PDF viewer. Similarly, you can also watch the PDF output:

typst watch --features bundle,html --format pdf dist.typ

Instead of opening a local development server, Typst writes into the PDF file every time you modify the .typ source.

typst watch is very fast for both PDF and HTML output. This is because Typst uses incremental compilation for recompilations.

Architecture

The documentation system has two parts: the organizer, which is the book function, and the renderer.

The book function will organize the content into a tree, and that tree is then fed into the renderer. The renderer will take a tree, inspect it, then generate pages based on that tree. This means that writing your own renderer is trivial. You can swap to a different renderer at any time.