1. Introduction
  3. User Guide
  4. 1. Installation
  5. 2. Get Started
  6. 3. Frequently Asked Questions
  7. 4. Further reading
  9. Reference Guide
  10. 5. Command Line Tool
    1. 5.1. init
    2. 5.2. build
    3. 5.3. serve
    4. 5.4. clean
    5. 5.5. completions
  12. 6. Format
    1. 6.1. book.typ
      1. 6.1.1. Book Metadata
        1. 6.1.1.1. Draft chapter
      3. 6.1.2. Build Metadata
    3. 6.2. Theme
    4. 6.3. Typst Support
      1. 6.3.1. Cross Reference
        1. 6.3.1.1. Cross Reference Sample
      3. 6.3.2. Embed Sanitized HTML Elements
        1. 6.3.2.1. Multimedia components
      5. 6.3.3. Semantic Page Description
  14. 7. For developers
    1. 7.1. Typst-side APIs
    2. 7.2. shiroa CLI Internals
    3. 7.3. Alternative Backends

shiroa

#

Creating a Book

Once you have the shiroa CLI tool installed, you can use it to create and render a book.

#

Initializing a book

The shiroa init command will create a new directory containing an empty book for you to get started. Give it the name of the directory that you want to create:

1
shiroa init my-first-book
1
shiroa init my-first-book

It will emit template files to the my-first-book. Then, you can change the current directory into the new book:

1
cd my-first-book
1
cd my-first-book

There are several ways to render a book, but one of the easiest methods is to use the serve command, which will build your book and start a local webserver:

1
shiroa serve
1
shiroa serve

Check out the shiroa help for more information about other shiroa commands and CLI options.

#

Anatomy of a book

A book is built from several files which define the settings and layout of the book.

#

book.typ

If you are familiar with mdbook, the book.typ file is similar to the book.toml with summary.md file.

The book source file is the main file located at src/book.typ. This file contains a list of all the chapters in the book. Before a chapter can be viewed, it must be added to this list.

Here's a basic summary file with a few chapters:

1
#import "@preview/shiroa:0.2.2": *
2
#show: book
3

4
#book-meta( // put metadata of your book like book.toml of mdbook
5
  title: "shiroa",
6
  description: "shiroa Documentation",
7
  repository: "https://github.com/Myriad-Dreamin/shiroa",
8
  authors: ("Myriad-Dreamin", "7mile"),
9
  language: "en",
10
  summary: [ // this field works like summary.md of mdbook
11
    = Introduction
12
    - #chapter("guide/installation.typ", section: "1.1")[Installation]
13
    - #chapter("guide/get-started.typ", section: "1.2")[Get Started]
14
      - #chapter(none, section: "1.2.1")[Drafting chapter]
15
  ]
16
)
1
#import "@preview/shiroa:0.2.2": *
2
#show: book
3

4
#book-meta( // put metadata of your book like book.toml of mdbook
5
  title: "shiroa",
6
  description: "shiroa Documentation",
7
  repository: "https://github.com/Myriad-Dreamin/shiroa",
8
  authors: ("Myriad-Dreamin", "7mile"),
9
  language: "en",
10
  summary: [ // this field works like summary.md of mdbook
11
    = Introduction
12
    - #chapter("guide/installation.typ", section: "1.1")[Installation]
13
    - #chapter("guide/get-started.typ", section: "1.2")[Get Started]
14
      - #chapter(none, section: "1.2.1")[Drafting chapter]
15
  ]
16
)

Try opening up src/book.typ in your editor and adding a few chapters.

#

Source files

The content of your book is all contained in the src directory. Each chapter is a separate Typst file. Typically, each chapter starts with a level 1 heading with the title of the chapter.

1
= My First Chapter
2

3
Fill out your content here.
1
= My First Chapter
2

3
Fill out your content here.

The precise layout of the files is up to you. The organization of the files will correspond to the HTML files generated, so keep in mind that the file layout is part of the URL of each chapter.

All other files in the src directory will be included in the output. So if you have images or other static files, just include them somewhere in the src directory.

#

Publishing a book

Once you've written your book, you may want to host it somewhere for others to view. The first step is to build the output of the book. This can be done with the shiroa build command in the same directory where the book.toml file is located:

1
shiroa build
1
shiroa build

This will generate a directory named book which contains the HTML content of your book. You can then place this directory on any web server to host it.

#

(Experimental) Using Typst v0.13.0's HTML Export

You don't have to change the default template, which already handles the HTML export. Simply set the mode to static-html to export the book as Static HTML files:

1
shiroa build --mode static-html
1
shiroa build --mode static-html

You are viewing the HTML export of the book right now :). See the Paged version of shiroa's documentation to see the result using the old paged export.

There is still some known issues, for example, typst hasn't support labels in the HTML export yet.