Configuration

Book configuration is done inside the [nimibook] section of nimib.toml configuration file.

Here are the available fields:

  • title (string): Title of the book
  • language (string): The main language of the book, which is used as a language attribute <html lang="en"> for example (defaults to en)
  • description (string): A description for the book, which is added as meta information in the html of each page
  • default_theme (string): The theme color scheme to select by default in the 'Change Theme' dropdown. Defaults to light.
  • preferred_dark_theme (string): The default dark theme. This theme will be used if the browser requests the dark version of the site via the 'prefers-color-scheme' CSS media query. Defaults to navy.
  • git_repository_url (string): A url to the git repository for the book. If provided an icon link will be output in the menu bar of the book.
  • git_repository_icon (string): The FontAwesome icon class to use for the git repository link. Defaults to fa-github.
  • plausible_analytics_url (string): (new in nimibook) if non empty it will include plausible analytics script in every page.
  • favicon_escaped (string): (new in nimibook) provide your fully custom <link rel="icon" href="...">. defaults to whale emoji as in nimib.

As an example here is nimibook configuration:

[nimib]
srcDir = "book"
homeDir = "docs"

[nimibook]
language = "en-us"
title = "Nimibook"
description = "Nimibook documentation"
git_repository_url = "https://github.com/pietroppeter/nimibook"
plausible_analytics_url = "pietroppeter.github.io/nimibook"

This is the default configuration created by the init command:

[nimibook]
language = "en-us"
title = "My book"
description = "a book built with nimibook"

Folder structure

By default the nimibook folder structure is to put all sources in a book folder and to put the book built output in a docs folder (so that it is straightforward to publish the book with github pages).

These folders can be customized since they are taken from [nimib] section of nimib.toml as srcDir and homeDir.

where does nimibook puts the output html?

The logic of nimibook is that for every source, the relative path with respect to srcDir is applied as relative path to homeDir and this will give the html output path. For example, if we have default values srcDir="book";homeDir="docs":

  • a source in book\example.md will generate docs\example.html
  • a source in book\folder\subfolder\example.nim will generate docs\folder\subfolder\example.html

Note in particular that if you have this structure in root folder:

README.md
img.png
book/
  example.nim
docs/
  ...

and you add ..\README.md as source, the generated README.html will NOT be in docs folder and it will be next to README.md (since docs is a folder inside root folder, at the same level as book). You can override this behaviour in nbook.nim but if the README.md references an image (say img.png) you will also need to make a copy of img.png in the docs folder.

Additional remarks