kerrycobb / nimibook

A port of mdbook to nim(ib)

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 itself.

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.

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 the [cheatsheet].

Status

nimibook currently provides minimal functionality to create a book and support a local CLI mode.

Installation

To install Nimibook simply use : nimble install nimibook

Usage

1. Write your content using nimib or simple markdown files in the book folder.

2. Use the Table of Content (ToC) DSL to link chapters to content in nbook.nim. Example :

import nimibook

var book = newBookFromToc("Dummy Book", "book"): # Create a new book called "Dummy", whose content is in the folder "book"
  section("Dummy", "index"): # Create a new section called "Dummy", its content is the file "index.nim". Notice how the .nim extensions is optionnal
    entry("Simple example", "page_1.nim") # Create a new entry called "Simple example", its content is the file "page_1.nim"

nimibookCli(book)

See nimibook or Nimibook repo for more documentations and examples.

3. Generate your very own CLI tools or use Nimble tasks with nim c -d:release nbook.nim.

• ./nbook init to init your book structure. This command must be ran at least once.
• ./nbook build to build your book.

4. Whenever your Table of Content changes (add/remove files, changes sections organization), recompile your nbook and run the build command : nim c -d:release nbook.nim && ./nbook build

• It is also doable in one command : nim r -d:release nbook.nim build
• You don't need to call the init command again.
• Rinse and repeat until your ToC is done ! Then you can just edit files and call build without recompiling.

Tips and Tricks

• Each book requires its own ToC and thus will be its own CLI Apps
• nbook.nim is the default name used - it is possible to use another name.
• Multiple books nbook.nim cannot share the same folder. Instead, either split them into two separate books, or merge them into one.
• Some commands :
  • ./nbook clean will remove generated files and restart from a clean state.
  • ./nbook update will update assets and mustache template.
  • These two commands will modify installed files, use them with caution if you customized files locally.

Analytics

This website is tracking analytics with plausible.io, a lightweight and open-source website analytics tool with no cookies and fully compliant with GDPR, CCPA and PECR. Analytics for this website are publicly available here. You can opt out from analytics tracking with standard ad-blocking or typing localStorage.plausible_ignore=true in browser console.