A port of mdbook to nim(ib)
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).
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.
You are welcome to open a PR and add your site using nimibook here.
To install Nimibook: nimble install 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:
nimib.toml
that contains the default configuration for the bookbook
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.docs
folder that contains static assets for the book
and that will contain the built book4. 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.
See nimibook documentation for more details.
You are more than welcome to contribute!
nimble tasks
for the list).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.