ProgBook

Use mdBook/MkDocs/Docsify to generate a book from my programming notes.

This repository is used for learning how to use mdBook/MkDocs to generate a nice online book. The content sources are not contained in this repository.

About writing in Markdown.

Preparation

Install Python Runtime Environment

condapack --file requirements.pip progbook #*

*: condapack is a self-made conda-wrapper. You can create the environment by directly call conda:

conda create -n progbook --file requirements.pip

Configure the Source

All the necessary referred Markdown documents are specified in mkdocs.yml (MkDocs), and we will convert the content so that it can be referred by other tools. For example, you can run the following command to generate files that needed by mdBook:

conda run --name progbook --no-capture-output python bin/checksource.py > src/SUMMARY.gen.md

Based on the convert output, you can identify if some linked source folder is missing in local file system, and update the sources.conf file with the right source folder. Then, run the following command to link the source folders into the workspace.

./bin/linksrc.sh

And then rerun the checksource.py.

Find Your Documents

List all the markdown files in the folder:

tree -l -P '*.md' src | grep -v '.gen.md' | head -n -1 > mydocs.$(date +%F).txt

Then, add extra items to your book specification files (mkdocs.yml). You can save the above result, and then next time compare it with new results to find what changes.

You may need to rerun checksource.py as above to reconfigure the source.

Usage of mdBook

Install mdBook

Install and update mdBook and the used plugins:

./bin/install-mdbook.sh

Integrated Plugins for mdBook

• mdbook-katex
• mdbook-mermaid
• mdbook-theme
• ...

Build the Book

run html service locally to serve documents:

mv src/SUMMARY.gen.md src/SUMMARY.md  # compare the index file
mdbook serve [path/to/book]  # watch file changes*

*: path/to/book is the folder containing book.toml, default is current working directory. .gitignore files in the root of the book directory specifies the files that should be excluded from watch.

or output html files and then put it on other web servers.

mdbook build
mdbook watch path/to/book  # watch file changes and rebuild the book*

Export the Build

./bin/syncbook.sh mdbook

Usage of MkDocs

Make sure all referred Markdown documents are put into the docs folder, or softly linked from the docs folder.

run html service locally to serve documents:

mkdocs serve

or output html files and then put it on other web servers.

mkdocs build

MkDocs Plugins

pip install mkdocs-foo-plugin

Third party extensions.

Usage of Docsify

Install Docsify

sudo npm i docsify-cli -g

Integrated Plugins for Docsify

• docsify-autoHeaders (modified);
• docsify-mermaid
• docsify-tabs
• docsify-sidebar-collapse
• docsify-latex (KaTeX/MathJax)
• docsify-progress
• docsify-image-caption
• prism

Compile Document Source via Docsify

conda run --name progbook --no-capture-output python bin/checksource.py --style docsify > docs/README.gen.md
conda run --name progbook --no-capture-output python bin/checksource.py --style docsify_sidebar > docs/_sidebar.gen.md
# after comparing changes.
mv docs/README.gen.md docs/README.md
mv docs/_sidebar.gen.md docs/_sidebar.md
SOURCE_DIR=docs ./bin/linksrc.sh
./bin/docsify-compile.py --clean --offline
docsify serve .build

Deploy as Static Site

Upload the content of .build to an HTTP server's static resource path, then the site can be visited via that server. The resource path on HTTP server should be consistent with the configuration basePath in index.html. For example, we set it to be /docsify/ by default, and the access URL should be http://server-site:port/docsify/"。

For demonstration purpose, we can simply link the content into the deploy location:

BASE_PATH=/docsify
mkdir -p ~/usr/share/html && ln -svf --no-dereference $(realpath .build) "${HOME}/usr/share/html${BASE_PATH}"
conda run --name progbook --no-capture-output python -m http.server --bind 0.0.0.0 --directory ~/usr/share/html 8000

Export the Docsify Build

./bin/syncbook.sh docsify

Issues

Current Issues of Using mdbook

1. Cannot render math equations with $...$ notations.

   • Official Notes: MathJax Support
   • The issue post: Improve MathJax support by enabling $$ for math equations (#400)

   Fix: solved with mdbook-katex, replacing MathJax, but KaTeX itself has other issues.

2. Does not support text highlight with ==...==.

Current Issues of Using MkDocs

1. 引用块中包含的代码块不能正确被渲染。

Current Issues of Using Docsify

1. Does not support text highlight with ==...==.

2. Does not support nesting bold and italic text. ***...***。

3. relative path in sidebar changes its base path when the opening document changes.

   Fix: use absolute path for sidebar, only use relative path's in documents.

4. sidebar file should not contain headers, otherwise these headers will be repeatedly added to the sub-nodes when /_sidebar.md is shared by all sub-folders.

   Fix: Do not write headers in _sidebar.md, instead, write multi-level lists to reflect content hierarchy.

5. When used with docsify-sidebar-collapse, the link on parent nodes is invalid. The click event triggers collapse/expand.

   Note: no need to fix as this is the expected behavior.

6. Relative paths in HTML elements are not converted to unified absolute URLs.

   Fix: convert source to replace the relative path in embedded HTML elements.

7. Footnote plugin coincide with regex pattern [^abc].

   Note: disable the plugin.

Common Issues on Using KaTeX to Render Equations

1. KaTeX cannot properly render display equations in quote text (==no discussion on the internet==).

2. KaTeX missing support for some latex commands, such as \abs.

   See Supported Functions for supported LaTeX commands.

   Fix: using customized latex macros for katex (depends on the renderer who use KaTeX, the configuration methods vary).

3. For KaTeX to work properly: Subscripts including commands should be put into {...} block.

4. KaTeX not support \label and \ref/\eqref.

   • KaTeX/KaTeX#2798
   • KaTeX/KaTeX#2003

   Fix:

   • use customized macro to renew \label and \ref/\eqref.
   • does not include _ (underscore) in label string.