@atom-forge/bookmd · Documentation
Write Markdown. Publish a book.
BookMD turns Markdown files into a static book collection on the web. Every AtomForge package documents itself as a BookMD book, and the books are gathered on one site.
What it is
Documentation that lives next to the code.
A book is a set of Markdown files with a defined structure and metadata. BookMD builds them into a static site, so there is no server to run and the result can be hosted anywhere that serves files.
A collection lists its books in content/books.md. A book can come from the same repository or from another GitHub repository, including a private one, so each package can keep its documentation beside its source while one site publishes them all.
Why choose BookMD?
Plain Markdown
Chapters are ordinary Markdown files that you can review in a pull request like any other change.
Books from many repositories
A collection can include books that live in other GitHub repositories, external or private, and rebuilds them from their main branches.
Publish on GitHub Pages
Use the template repository, a user site, or your own domain with a CNAME record and the Pages custom-domain setting.
Or host it yourself
The output is a static build. Upload it to your own server when GitHub Pages is not an option.
How it works
-
Write the chapters
Add Markdown files with the metadata BookMD expects, one file per chapter.
-
List the book in a collection
Add the book as a source in content/books.md and choose its address with slug.
-
Build and publish
Preview locally with the bookmd command line, then publish through GitHub Pages or upload the static build.
An honest fit check
Trade-offs, not fine print
Static output
A book is built ahead of time. A change in an included book appears after the next collection build.
Private books need access
Reading a private repository requires credentials, for example a GitHub App installed on that repository.
In practice
A collection of books
content/books.md lists the books of a collection. The source points at a book file in a repository; slug sets its address.
- source: "main@github.com/atom-forge/laminar/book/book.md"
slug: laminar