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.
nimibook currently provides minimal functionality to create a book and support a local CLI mode.
To install Nimibook simply use :
nimble install nimibook
Write your content using nimib or simple markdown files in the
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)
- Generate your very own CLI tools or use Nimble tasks with
nim c -d:release nbook.nim.
./nbook initto init your book structure. This command must be ran at least once.
./nbook buildto build your book.
- Whenever your Table of Content changes (add/remove files, changes sections organization), recompile your
nbookand run the
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
- Rinse and repeat until your ToC is done ! Then you can just edit files and call
Tips and Tricks
- Each book requires its own ToC and thus will be its own CLI Apps
nbook.nimis the default name used - it is possible to use another name.
- Multiple books
nbook.nimcannot share the same folder. Instead, either split them into two separate books, or merge them into one.
- Some commands :
./nbook cleanwill remove generated files and restart from a clean state.
./nbook updatewill update assets and mustache template.
- These two commands will modify installed files, use them with caution if you customized files locally.
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 with a simple command in browser console: https://plausible.io/docs/excluding-localstorage