mdBook Installation and Usage Guide

Installation Guide

The easiest method for installing mdBook on your particular operating system is to download the executable binary file from the mdBook GitHub Releases page.

Once you have downloaded the file, extract it in your preferred method and run the executable.

In the Windows zip file there is a .exe file for you to use.

For Mac users, there is a tar ball for you to use.

In the Linux .tar.gz file, open a shell in the folder you want to extract the executable file, and use the following command to download and extract the executable file.

wget -O- https://github.com/rust-lang/mdBook/releases/download/v0.4.15/mdbook-v0.4.15-x86_64-unknown-linux-gnu.tar.gz | tar xzvf -

The commands

The commands used in the wget are as follows:

• We can use -O- to send to STDOUT (the standard out)
• We use the pipe | to pipe it into the tar ball using
  • tar xzvf -
  • Which essentially does an un-gz on the tar ball
• v is verbose (i.e. the type of output you produce)
• f is file (in this case it was the STDOUT file)
  • So the tar ball was extracted out from the STDOUT file
  • The STDOUT of wget became the STDIN for the tar ball
• Important: The final dash - is to extract from the STDOUT

After extraction

In your shell run ./mdbook

This will install mdbook on your local machine.

➜ user@name  ~  ./mdbook 
mdbook v0.4.15
Mathieu David <mathieudavid@mathieudavid.org>
Creates a book from markdown files

USAGE:
    mdbook [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    build          Builds a book from its markdown files
    clean          Deletes a built book
    completions    Generate shell completions for your shell to stdout
    help           Prints this message or the help of the given subcommand(s)
    init           Creates the boilerplate structure and files for a new book
    serve          Serves a book at http://localhost:3000, and rebuilds it on changes
    test           Tests that a book's Rust code samples compile
    watch          Watches a book's files and rebuilds it on changes

For more information about a specific command, try `mdbook <command> --help`
The source code for mdBook is available at: https://github.com/rust-lang/mdBook

How to use mdBook

Clone the GitHub Repo to your local machine and open it in your code editor of choice and make a new branch for yourself.

The Table of Contents on the left side of the website is created in the SUMMARY.md file.

If you want to add a new section, the follow the styling in the SUMMARY.md file to add your new page.

How to add a new section

// The "#" represents a H1 tag
# Heading Of Your New Section

// dash is an unordered list. 
- Unordered List
- Unordered List

// Inside the [ ] is the hyperlink name and inside the ( ) is the hyperlink path.
[New Subsection Name](Heading Of Your New Section/NewFileName.md) 

Now, save and run mdbook build in your shell and your new section and file will automatically appear in the Table of Contents.

Open the file that you have just created and write your content using Markdown.

Useful sites about using Markdown

• markdown-it
• Daring Fireball

Once you have finished creating your content save and run mdbook build in your shell again.

This creates all of the HTML files that will be displayed on the website.

How to add your changes to GitHub and deploy to Vercel

VS Code

• Stage the files you made changes to and add a meaningful comment.
• Push your files to GitHub

Command Shell

Use the following commands to add your changes:

git commit -m "Add_A_Meaningful_Comment" file_you_changed_1 file_you_changed_2 ...
git push -u origin [the name of the branch you are currently working on]  // without the [ ]

There is a GitHub Action in the yama-documentation repo that will automatically build and deploy your changes once you push them to Github.

What is in the src folder

The src folder contains all of the markdown files that are shown on the documentation site.

When you want to edit a page, this is where you can do that.

The book folder contains all of the HTML files that are automatically produced when mdbook build is run.

You only need to run mdbook build if you are testing on your local machine.

You should have book/.* in your .gitignore file.

Call-out styling with mdbook-admonish

mdbook-admonish is a plugin for mdBook that will allow you to add Material UI style call-outs to your book.

Step 1

cd inside/your/project_folder

inside/your/project_folder: cargo install mdbook-admonish

Step 2

Install the required files and configuration code using:

inside/your/project_folder: mdbook-admonish install

These two configuration settings will be added to your book.toml file.

[preprocessor.admonish]
command = "mdbook-admonish"

[output.html]
additional-css = ["./mdbook-admonish.css"]

Step 3

Copy the file mdbook-admonish.css into the book directory of your project if it's not already there.

Step 4

Build your book using:

inside/your/project_folder: mdbook