A Recommended Markdown Tool for Writing Books — Possibly a GitBook Alternative

wzdushu@gmail.com (wanzi) — Thu, 06 Oct 2022 21:38:52 +0800

Introduction to mdBook

mdBook is a command-line tool written in Rust for creating books using Markdown. It’s ideal for crafting product or API documentation, tutorials, course materials, or any content requiring a clean, navigable, and customizable presentation. Functionally similar to GitBook, its greatest advantage lies in speed.

Lightweight, Markdown-based syntax
Built-in search functionality
Syntax highlighting
Multiple themes for customizing output appearance
Preprocessors support — extend markdown rendering by modifying content before processing
Backend support for multiple output formats
Speed — built with Rust, performance is excellent
Even supports automated testing of Rust code

Installing mdBook

Since mdBook is developed in Rust, you need to install Rust first.

Install Rust:

# curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
......
Rust is installed now. Great!

To get started you may need to restart your current shell.
This would reload your PATH environment variable to include
Cargo's bin directory ($HOME/.cargo/bin).

To configure your current shell, run:
source "$HOME/.cargo/env"
# cargo version
cargo 1.65.0 (4bc8f24d3 2022-10-20)

After installing Rust, build and install mdBook via the command line. Once completed:

# cargo install mdbook
    Updating crates.io index
  Installing mdbook v0.4.21
  Downloaded os_str_bytes v6.4.0
  Downloaded chrono v0.4.23
  Downloaded 2 crates (210.4 KB) in 1.30s
  ......
   Compiling libc v0.2.137
   Compiling mdbook v0.4.21
    Finished release [optimized] target(s) in 1m 12s
  Installing /Users/wanzi/.cargo/bin/mdbook
   Installed package `mdbook v0.4.21` (executable `mdbook`) # Indicates successful installation
# mdbook --version
mdbook v0.4.21
# tree -L 2 ~/.cargo
/Users/wanzi/.cargo
├── bin
│   ├── cargo
│   ├── cargo-clippy
│   ├── cargo-fmt
│   ├── cargo-miri
│   ├── clippy-driver
│   ├── mdbook # Confirms installation
│   ├── rls
│   ├── rust-gdb
│   ├── rust-gdbgui
│   ├── rust-lldb
│   ├── rustc
│   ├── rustdoc
│   ├── rustfmt
│   └── rustup
├── env
└── registry
    ├── CACHEDIR.TAG
    ├── cache
    ├── index
    └── src

If you want the latest version, use this method instead:

`1`	`cargo install --git https://github.com/rust-lang/mdBook.git mdbook`

Writing an eBook with mdBook

Initialize a new book named devops-manual:

# mdbook init devops-manual
Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
devops-manual
2022-10-06 13:59:33 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...
# tree devops-manual
devops-manual
├── book
├── book.toml
└── src
    ├── SUMMARY.md
    └── chapter_1.md

2 directories, 3 files

Start mdBook to preview locally:

# mdbook serve --open
2022-10-06 14:04:05 [INFO] (mdbook::book): Book building has started
2022-10-06 14:04:05 [INFO] (mdbook::book): Running the html backend
2022-10-06 14:04:05 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000
2022-10-06 14:04:05 [INFO] (mdbook): Opening web browser
2022-10-06 14:04:05 [INFO] (warp::server): Server::run; addr=127.0.0.1:3000
2022-10-06 14:04:05 [INFO] (warp::server): listening on http://127.0.0.1:3000
2022-10-06 14:04:05 [INFO] (mdbook::cmd::watch): Listening for changes...

The --open flag automatically opens your default web browser to view the book.

Directory Structure of a New mdBook Project

book.toml: Configuration file describing how to build the eBook, written in TOML format
SUMMARY.md: Located at src/SUMMARY.md, this file lists all chapters in the book. You must add each chapter here before it can be viewed.
src: Contains the source files for the book. Each chapter has its own Markdown file.
book: Stores the generated HTML files. After running mdbook build, static files for the eBook are generated here, ready to be hosted on services like GitHub Pages.

Now, to write a DevOps eBook, simply define your structure, then write each chapter one by one.

For example, here’s my devops-manual/SUMMARY.md:

# Summary

[Introduction](README.md)

# DevOps Engineering

- [DevOps](xops/devops.md)

# DevOps Toolchain

- [Basic Tools](base/readme.md)
  - [Git](base/git.md)
  - [Docker](base/docker.md)
  - [Makefile](base/makefile.md)

- [Product Requirements](project/readme.md)
  - [Jira](project/jira.md)
  - [PingCode](project/jira.md)

- [Code Management](code/readme.md)
  - [GitLab](code/gitlab.md)
  - [GitHub](code/github.md)
  - [Gerrit](code/Gerrit.md)

- [Testing & Security Scanning](test/readme.md)
  - [JMeter](test/jmeter.md)
  - [SonarQube](test/sonarqube.md)
  - [Black Duck](test/blackduck.md)
  - [Fortify](test/fortify.md)

- [Build & Compilation](makebuild/readme.md)
  - [Maven](makebuild/maven.md)
  - [Gradle](makebuild/gradle.md)
  - [Node](makebuild/node.md)
  - [NPM](makebuild/npm.md)
  - [Cargo](makebuild/cargo.md)

- [Artifact Repository](hub/readme.md)
  - [Harbor](hub/harbor.md)
  - [Nexus](hub/nexus.md)
  - [JFrog Artifactory](hub/jfrog.md)

- [Automated Deployment](autodeploy/readme.md)
  - [Ansible](autodeploy/ansible.md)
  - [ArgoCD](autodeploy/argocd.md)
  - [Helm](autodeploy/helm.md)
  - [Kustomize](autodeploy/kustomize.md)

- [Logging & Monitoring Stack](logmonitor/readme.md)
  - [EFK](logmonitor/efk.md)
  - [Prometheus](logmonitor/prometheus.md)
  - [Grafana](logmonitor/grafana.md)
  - [Loki](logmonitor/loki.md)
  - [SkyWalking](logmonitor/skywalking.md)
  - [Jaeger](logmonitor/jaeger.md)
  - [Pinpoint](logmonitor/pinpoint.md)

- [Other Tools](others/readme.md)
  - [Rancher](others/rancher.md)
  - [JumpServer](others/jumpserver.md)
  - [Nacos](others/nacos.md)
  - [Consul](others/consul.md)
  - [Traefik](others/apisix.md)
  - [API7](others/apisix.md)
  - [Terraform](others/terraform.md)
  - [Pulumi](others/pulumi.md)
  - [Vault](others/vault.md)

- [Programming Languages](language/readme.md)
  - [Shell](language/shell.md)
  - [Python](language/python.md)
  - [Golang](language/golang.md)

- [Frameworks & Modules](framework/readme.md)
  - [Gin](framework/gin.md)
  - [Vue](framework/vue.md)
  - [React-antd](framework/antd.md)
  - [Django](framework/django.md)
  - [Bootstrap](framework/bootstrap.md)
  - [Swagger](framework/swagger.md)
  - [Postman](framework/postman.md)
  - [ApiPost7](framework/apipost7.md)
  - [RBAC](framework/rbac.md)
  - [JWT](framework/jwt.md)

- [XOPS](xops/xops.md)
  - [GitOps](xops/gitops.md)
  - [AI Ops](xops/aiops.md)
  - [MLOps](xops/mlops.md)
  - [FinOps](xops/finops.md)
  - [DevSecOps](xops/devsecops.md)
  - [DevDBOps](xops/devdbops.md)
  - [Chaos Engineering](xops/hundun.md)

After completing these steps, just run mdbook build, map the book directory to your Nginx root path, and configure the virtual host — isn’t that simple?

Rust on Wanzi's Blog – Notes on life, tech, and DevOps.

A Recommended Markdown Tool for Writing Books — Possibly a GitBook Alternative

Introduction to mdBook

Installing mdBook

Writing an eBook with mdBook

Directory Structure of a New mdBook Project