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
    6. 6.4. Rendering Tests
  14. 7. For developers
    1. 7.1. Typst-side APIs
    2. 7.2. shiroa CLI Internals
    3. 7.3. Alternative Backends

shiroa

#

The build command

The build command is used to render your book:


        
shiroa build

      

      

        

      

    

    

      

        

      

      

        

        
shiroa build

      

      

        

      

    

    
  

  
It will try to parse your book.typ file to understand the structure and metadata of your book and fetch the corresponding files. Note that files mentioned in book.typ but not present will be created.

  
The rendered output will maintain the same directory structure as the source for convenience. Large books will therefore remain structured when rendered.

  

    

      
#

    

    
Specify a directory

  

  
The build command can take a directory as an argument to use as the book's root instead of the current working directory.

  

    

      

        

      

      

        

        
shiroa build path/to/book

      

      

        

      

    

    

      

        

      

      

        

        
shiroa build path/to/book

      

      

        

      

    

    
  

  

    

      
#

    

    
–workspace, -w

  

  
Note: The workspace is a typst-specific command.

  
The --workspace option specifies the root directory of typst source files, which is like the --root option of typst-cli. It is interpreted relative to current work directory of shiroa process.

  
For example. When a book is created with the main file book-project1/book.typ, and you want to access a template file with path common/book-template.typ, please build it with following command:

  

    

      

        

      

      

        

        
shiroa build -w . book-project1

      

      

        

      

    

    

      

        

      

      

        

        
shiroa build -w . book-project1

      

      

        

      

    

    
  

  
Then you can access the template with the absolute path in typst:

  

    

      

        

      

      

        

        
#import "/common/book-template.typ": *

      

      

        

      

    

    

      

        

      

      

        

        
#import "/common/book-template.typ": *

      

      

        

      

    

    
  

  

    

      
#

    

    
–dest-dir, -d

  

  
The --dest-dir (-d) option allows you to change the output directory for the book. Relative paths are interpreted relative to the book's root directory. If not specified it will default to the value of the build.build-dir key in book.toml, or to ./book.

  

    

      
#

    

    
–path-to-root

  

  
When your website's root is not exact serving the book, use --path-to-root to specify the path to the root of the book site. For example, if you own myriad-dreamin.github.io and have mounted the book to /shiroa/, you can access https://myriad-dreamin.github.io/shiroa/cli/main.html to get the generated content of cli/main.typ.

  

    

      

        

      

      

        

        
shiroa build --path-to-root /shiroa/ book-project1

      

      

        

      

    

    

      

        

      

      

        

        
shiroa build --path-to-root /shiroa/ book-project1

      

      

        

      

    

    
  

  

    

      
#

    

    
–mode

  

  
The --mode option allows you to specify the mode of rendering typst document. The default mode is normal.

  
    
    
  • (Default) dynamic-paged: dynamically render as paged document.
    • 
    
  • (Experimental) static-html: statically render the whole document, the embedded frames are not resizable.
    • 
    
  • (Todo) static-html-static-paged: statically render html parts as much as possible, and leave frames rendered dynamically.
    • 
  

  
The dynamically rendering means that some elements will be rendered by a wasm renderer in the browser.

  

    

      
#

    

    
–theme

  

  
Specify a theme directory to copy recursively. This allows you to use custom themes.

  
The files will be copied to the theme/ in the output directory.

  
The default theme is located at themes/mdbook. You can start by copying this theme and modifying it to your needs.

  
Currently, no interface is designed for custom themes, i.e. everything is working occasionally. If you have any questions, design or feature requests about theming, please open an issue in the repository.