Table of contents
introduce
mdBook is a command-line tool for creating books using Markdown. It's perfect for creating product or API documentation, tutorials, course materials, or any presentation that needs to be clear, easy to navigate, and customizable.
- Lightweight Markdown syntax helps you focus more on your content
- Comprehensive search support
- Color syntax highlighting for code blocks in many different languages
- Theme files allow for custom output formats
- Preprocessors can provide extensions for custom syntax and modification
- The backend can render the output to a variety of formats
- Written in Rust for speed, safety and simplicity
- Automated testing of Rust code examples
The official github address of mdBook: mdBook
1. Download and create project
1. Download
Depending on your operating system, go to the mdBook releases page and download the latest mdBook package.
or
Baidu cloud windos version download (link: https://pan.baidu.com/s/1nd1343_nmaZBu_ogcWaN1Q extraction code: isjq )
What I downloaded here is mdbook-v0.4.30-x86_64-pc-windows-msvc.zip.
2. Initialization
After decompressing the compressed package, open the cmd command line in the folder where mdbook.exe is located, and execute the following command to initialize:
mdbook.exe init ./mybook
When initializing, give your tree or project a name. I named it mybook above, and then it will ask you if you want to create a .gitignore and title directory, which can be entered as needed. Finally, the following project directory will be generated:
mybook/
├── book
├── book.toml
└── src
├── chapter_1.md
└── SUMMARY.md
3. Structure description
-
book.toml is your configuration file, which can configure the unified title, path, author and other information at the top of each article.
-
All your new Markdown articles should be placed in the src directory.
-
Summary.md is the directory of all your articles, and all your new Markdown articles need to be configured in it.
-
Don't worry about the book folder, and finally mdBook will automatically generate some html files in it after startup.
2. Write articles and launch
1. Write an article
Now you can write your own Markdown articles in the src directory, and then add the article name in the Summary.md directory file.
2. build
Use the following build command to generate some final html files in the book directory of your project:
mdbook.exe build D:\Program\mdbook\mybook\
You can open index.html in the book directory to view the effect. You can also put the book directory on your server and map it to the nginx directory, and configure the virtual host to have your own e-book or blog document.
3. Start the mdbook service
You can also start the mdbook service:
mdbook.exe serve D:\Program\mdbook\mybook\
When it starts, it will first execute the build command, and then open port 3000. After the startup is successful, you can visit it with a browser http://localhost:3000and see the effect locally.
The effect is as follows:
3. Other configurations
For other configurations of mdBook, you can refer to the official operation document: mdBook document