CLI Init Command

The initinit command creates a new book directory with starter files, then builds and serves it with the same preview server used by shiroa serveshiroa serve. The target directory must not already exist.

Since initinit builds the generated project after creating it, the build options are available for initinit too.

For instance, Initialize a book to the directory my-bookmy-book:


shiroa init my-book/
shiroa build my-book/


shiroa init my-book/
shiroa build my-book/

Initialize a book with specific typst workspace directory:


shiroa init --root . my-book/
shiroa build --root . my-book/


shiroa init --root . my-book/
shiroa build --root . my-book/

Initialize a book with specific dest-dirdest-dir:


shiroa init --dest-dir ../dist my-book/
shiroa build my-book/ # remembered in book.typ


shiroa init --dest-dir ../dist my-book/
shiroa build my-book/ # remembered in book.typ

The older -w-w/--workspace--workspace option is deprecated. Use --root--root instead.

Initializing a book project manually

This section describes what are required by shiroa to build a book successfully.

A book.typbook.typ file in the root that collects all metadata and chapter files of the book.
A template.typtemplate.typ file used by chapter files to render the page.
A sample chapter1.typchapter1.typ file shows how to use the template.typtemplate.typ.

shiroa will read book.typbook.typ file first to find metadata and all chapter files, and render them accordingly.

The sample files are from tests/minimaltests/minimal directory.

Note: The sample is minimal and lacks of many show rules and theme settings to make good output. To learn more, please check Typst SupportTypst Support.

your book.typbook.typ should at least provide a book-metabook-meta.


#import "@preview/shiroa:0.4.0": *
#show: book
#book-meta(
  title: "My Book",
  summary: [
    = My Book
    - #chapter("chapter1.typ", section: "1")[Chapter 1]
  ],
)


#import "@preview/shiroa:0.4.0": *
#show: book
#book-meta(
  title: "My Book",
  summary: [
    = My Book
    - #chapter("chapter1.typ", section: "1")[Chapter 1]
  ],
)

Your template.typtemplate.typ must import and respect the get-page-widthget-page-width and targettarget variable from @preview/shiroa:0.4.0@preview/shiroa:0.4.0 The two variables will be used by the tool for rendering responsive layout and multiple targets.


#import "@preview/shiroa:0.4.0": get-page-width, is-html-target, is-pdf-target, is-web-target, templates, x-target
#import templates: *
// Metadata
#let page-width = get-page-width()
#let is-html-target = is-html-target() // target.starts-with("html")
#let is-pdf-target = is-pdf-target() // target.starts-with("pdf")
#let is-web-target = is-web-target() // target.starts-with("web")
#let project(body) = {
  // set web/pdf page properties
  set page(
    width: page-width,
    // for a website, we don't need pagination.
    height: auto,
  ) if is-pdf-target or is-web-target
  // remove margins for web target
  set page(margin: (
    // reserved beautiful top margin
    top: 20pt,
    // Typst is setting the page's bottom to the baseline of the last line of text. So bad :(.
    bottom: 0.5em,
    // remove rest margins.
    rest: 0pt,
  )) if is-web-target
  let web-theme = if x-target.starts-with("html") and not x-target.starts-with("html-wrapper") {
    "starlight"
  } else {
    "mdbook"
  }
  show: if web-theme == "starlight" {
    import "@preview/shiroa-starlight:0.4.0": starlight
    starlight.with(include "book.typ")
  } else if web-theme == "mdbook" {
    import "@preview/shiroa-mdbook:0.4.0": mdbook
    mdbook.with(include "book.typ")
  } else {
    panic("Unknown web theme: " + web-theme)
  }
  body
}


#import "@preview/shiroa:0.4.0": get-page-width, is-html-target, is-pdf-target, is-web-target, templates, x-target
#import templates: *
// Metadata
#let page-width = get-page-width()
#let is-html-target = is-html-target() // target.starts-with("html")
#let is-pdf-target = is-pdf-target() // target.starts-with("pdf")
#let is-web-target = is-web-target() // target.starts-with("web")
#let project(body) = {
  // set web/pdf page properties
  set page(
    width: page-width,
    // for a website, we don't need pagination.
    height: auto,
  ) if is-pdf-target or is-web-target
  // remove margins for web target
  set page(margin: (
    // reserved beautiful top margin
    top: 20pt,
    // Typst is setting the page's bottom to the baseline of the last line of text. So bad :(.
    bottom: 0.5em,
    // remove rest margins.
    rest: 0pt,
  )) if is-web-target
  let web-theme = if x-target.starts-with("html") and not x-target.starts-with("html-wrapper") {
    "starlight"
  } else {
    "mdbook"
  }
  show: if web-theme == "starlight" {
    import "@preview/shiroa-starlight:0.4.0": starlight
    starlight.with(include "book.typ")
  } else if web-theme == "mdbook" {
    import "@preview/shiroa-mdbook:0.4.0": mdbook
    mdbook.with(include "book.typ")
  } else {
    panic("Unknown web theme: " + web-theme)
  }
  body
}

Your chapter1.typchapter1.typ should import and use the template.typtemplate.typ, as follow:


#import "template.typ": *
#show: project
= Chapter 1
This is the first chapter of the book.


#import "template.typ": *
#show: project
= Chapter 1
This is the first chapter of the book.