nimibook

nimibook is a port of mdbook to Nim, powered by nimib. Nimibook allows to create a nice looking book from nim code and markdown, making sure that nim code is running correctly and being able to incorporate code outputs in the final book. An example book is nimibook documentation.

mdBook is a command line tool and Rust crate to create books using Markdown (as by the CommonMark specification) files. It's very similar to Gitbook, which is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).

nimib is a Nim library to convert your Nim code and its outputs to html documents. The html output can be easily customized thanks to nim-mustache, and this is what allows it to use it to build nimibook. nimib documents are normal nim files which use nimib library to produce an output document.

One particular advantage of nimib is that it can incorporate interactive content taking advantage of nim's js backend. For the basic examples see nimib interactivity doc.

The Markdown dialect supported by both nimib and nimibook is the subset of Github Flavored Markdown provided by nim-markdown. For a quick reference of supported syntax see this cheatsheet (created with nimib).

Status

Nimibook is actively maintained (target issues for 2023) and it provides the basic functionality needed to create a book with markdown and nimib sources. It still has some features missing from mdbook (see this issue).

To follow up on recent changes check the changelog.md.

Example sites using nimibook

• scinim/getting-started
• moigagoo/norm
• PhilippMDoerner/Snorlogue
• PhilippMDoerner/mapster
• dsrw/enu

You are welcome to open a PR and add your site using nimibook here.

Features

• table of contents in a collapsible sidebar
• five themes (Light, Rust, Coal, Navy, Ayu)
• buttons to next/previous pages
• build multiple files in parallel
• (optional) latex content with katex
• (optional) link to github repo
• (optional) link to track analytics with plausible analytics

Installation

To install Nimibook: nimble install nimibook

How to setup your book with nimibook

Nimibook does not (yet) provides an executable to manage your book, but it provides the basic building blocks to write your own.

1. example nbook.nim: in a folder of your choice create a nbook.nim file with the following content:

import nimibook

var book = initBookWithToc:
  entry("Preface", "preface.md", numbered = false)
  entry("Introduction", "intro.md")
  section("Chapter 1", "chapter1/index.nim"):
    entry("Content", "content.nim")
    draft("Nothing yet")
    section("Sub chapter", "no_ext"):
      entry("and some more content", "more.md")

nimibookCli(book)

2. write a TOC: modify nbook.nim to specify the planned Table of Content (TOC) for your book.

3. nbook init: running nim r nbook init (or compile nbook and run nbook init) will set up the book with:

• a nimib.toml that contains the default configuration for the book
• a book folder that contains sources for all chapters mentioned in the TOC. Note that .nim files already contain default nimib content to be used in nimibook.
• a docs folder that contains static assets for the book and that will contain the built book

4. nbook build: run nim r nbook build to build the book. Open any .html file in docs folder to navigate your book.

5. create your content and enjoy!: now you are ready to start creating content in your sources and publish your book.