shiroa

Theme

In initinit command, we have provided a minimal template for you to start your book project. We recall that the template.typtemplate.typ file is used by chapter files to render the page, and in this section, we will show you how to make a feature rich template.

x-targetx-target

The sys.x-targetsys.x-target is specified by the shiroa, whose default value is pdfpdf. The valid values are:

  • pdfpdf: for PDF output (Paged Target).
  • webweb: for web output (Paged Target).
  • htmlhtml: for HTML output (HTML Target).
  • html-wrapperhtml-wrapper: for HTML output with a wrapper (HTML Target).

A target can be suffixed with a theme name to support specialized rendering for web pages, for example:

  • web-lightweb-light: for web output with a light theme.
  • web-ayuweb-ayu: for web output with a ayu (dark) theme.

How shiroa sets x-targetx-target

  1. In typst preview and webapp, since sys.x-targetsys.x-target is not set, we preview the book in pdfpdf target by default.

  2. When running shiroashiroa with --mode=static-html--mode=static-html, the sys.x-targetsys.x-target will be set to htmlhtml. Each page will be rendered as a static HTML file.

    For example, A page guide/get-started.typguide/get-started.typ will be compiled into guide/get-started.htmlguide/get-started.html.

  3. When running shiroashiroa with --mode=dyn-paged--mode=dyn-paged (default), shiroa will render a page with sys.x-targetsys.x-target set to html-wrapperhtml-wrapper, and then render the page with sys.x-targetsys.x-target set to webweb.

    For example, shiroa will render a page guide/get-started.typguide/get-started.typ to following artifacts:

    • guide/get-started.htmlguide/get-started.html: using typst compile guide/get-started.typ --input=x-target=html-wrappertypst compile guide/get-started.typ --input=x-target=html-wrapper
    • svg with light theme: guide/get-started.web-light.svgguide/get-started.web-light.svg: using typst compile guide/get-started.typ --input=x-target=web-lighttypst compile guide/get-started.typ --input=x-target=web-light
    • svg with ayu theme (and other themes): guide/get-started.web-ayu.svgguide/get-started.web-ayu.svg: using typst compile guide/get-started.typ --input=x-target=web-ayutypst compile guide/get-started.typ --input=x-target=web-ayu

Respecting x-targetx-target in your template

To apply set rules for different targets, your template.typtemplate.typ can import and respect the x-targetx-target variable from @preview/shiroa:0.3.1@preview/shiroa:0.3.1. For example, to remove margins for web target, you can do:

#import "@preview/shiroa:0.3.1": x-target
#let project(body) = {
  // 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 x-target.starts-with("web");
  body
}
#import "@preview/shiroa:0.3.1": x-target
#let project(body) = {
  // 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 x-target.starts-with("web");
  body
}

Creating a template for static-htmlstatic-html mode (Experimental)

There are samples to create components that utilize metadata from book.typbook.typ:

Creating a template for dyn-pageddyn-paged mode (Experimental)

Shiroa will pre-render multiple layouts by setting sys.page-widthsys.page-width and sys.x-targetsys.x-target to different values. A template must use page-widthpage-width to adjust the page width to avoid the content being cut off.

#import "@preview/shiroa:0.3.1": page-width, x-target
#let project(body) = {
  // set web/pdf page properties
  set page(width: page-width)
  set page(height: auto) if not x-target.starts-with("pdf");
  body
}
#import "@preview/shiroa:0.3.1": page-width, x-target
#let project(body) = {
  // set web/pdf page properties
  set page(width: page-width)
  set page(height: auto) if not x-target.starts-with("pdf");
  body
}

We know shiroa will render a page with sys.x-targetsys.x-target set to html-wrapperhtml-wrapper and webweb targets, so template must be aware of that. The html file (rendered with html-wrapperhtml-wrapper target) must contain a trampoline to load the svg file (rendered with webweb target). You can either create you owned trampoline or use the paged-load-trampolinepaged-load-trampoline function provided by shiroa:

#import "@preview/shiroa:0.3.1": paged-load-trampoline, x-target
#let html-template(trampoline) = html.html(
  html.head(html.title("Page Title")),
  html.body(trampoline),
)
#let project(body) = {
  let trampoline = paged-load-trampoline()
  if x-target.starts-with("html-wrapper") { html-template(trampoline) } else { body }
}
#import "@preview/shiroa:0.3.1": paged-load-trampoline, x-target
#let html-template(trampoline) = html.html(
  html.head(html.title("Page Title")),
  html.body(trampoline),
)
#let project(body) = {
  let trampoline = paged-load-trampoline()
  if x-target.starts-with("html-wrapper") { html-template(trampoline) } else { body }
}