I have been using the Gitbook command line tool to manage my documents and e-books, but it has long since stopped developing updates and has many bugs, and I have been looking for its replacement.

$gitbook --version CLI version: 2.3.2 gitbook version: 3.2.3Copy the code

Some problems with Gitbook

Link matching error

If the link contains), the generated link has a problem:

Paula [region] (Italian_province) (https://en.wikipedia.org/wiki/Pola_)Copy the code

Will become bora region), the right) as text, text corresponding to the link is wrong, should be the re written incorrectly. This problem is easily solved by using url encode:

Paula [region] (https://en.wikipedia.org/wiki/Pola_%28Italian_province%29)Copy the code

The footnote jump is invalid

If the footnote is a custom text, no error is reported during the generation and the footnote is displayed. However, it cannot be jumped.

In full expectation of victory.[^440.1] [^440.1]: Annals of Piacenza throw a new light on The history of ConradinCopy the code

Section267.html #fn_440.1 Footnote link is actually a fragment URL, but the browser can not jump, not sure whether the browser does not support this type of jump, the link generation process is wrong, or the format of personal writing is wrong (footnote can not be with.?). There is no time for research.

Multiple lines of footnotes are not supported

Many books also have paragraphs in their footnotes, such as:

This question was asked in 2016 and never solved! In this case, Markdown is not very expressive, even with pure HTML, but the most basic paragraphs should at least be supported. Hexo is supported, and the next paragraph of the footnote can be treated as part of the footnote as long as it begins with 4 Spaces as a block structure.

A solution found online that only works in Gitbook is to add a reference or list character after a paragraph:

> Que per valor et per noble coratge
>
> Mantenia W Enricx Vonrat linhalge
>
> De Colradi ah honrat vassalatge ;
>
> E'l reys W Anfos, ab son noble barutage
>
> Que a cor ric
>
> Den demandar tost sonfrair EN Enric,
>
Copy the code

Note that each subsequent line will still be concatenated into a paragraph without adding a single blank line, which is a bit ugly, but good enough to get to that point.

Vocabularies do not match)

One of my favorite features is gitbook’s GLOSSARY, which can annotate paragraphs of text in the text, display additional explanatory text by hovering over them, and help distinguish sentence structures and reduce ambiguities in long sentences.

However, words of the following form cannot be used as vocabulary keys:

## Heinrich (VII)
Copy the code

Estimate and link mismatch) is the same problem, however, cannot be solved with %29 this way, this is really not powerful, have to see the source code to know what is going on.

Vocabulary does not match non-English characters

Chinese place names cannot be used as vocabulary keys:

Personally escort prisoners to SAN Pietro Glossary.md near Palestrina:

## PalestrinaCopy the code

To achieve this effect, only add English words in the text and use English words as keys:

Personally escort prisoners to SAN Pietro near Palestrina, in Glossary.md:

## Palestrina is a commune in the metropolitan city of Rome, in the region of Lazio, Italy.Copy the code

In fact, this problem is precisely that words that do not end with English characters cannot be matched. If there are some characters in other languages, such as Brancaleone von Andalo, they cannot be used as vocabulary keys, but if there are characters in the middle, such as Connetable, there is no problem.

Slow build

Once you have a large number of chapters and files, Gitbook is slow. You have a book in multiple languages, 168 MD files in each language, plus a large vocabulary of words, and searching for matching text is incredibly slow, building it in 5 minutes.

Can’t hot update

Gitbook seems to come with liveload, which should automatically update files once they are modified, but it doesn’t. There may be a good plugin, but I haven’t looked for it carefully.

The PDF is very poor

Json file, the PDF file generated locally with Gitbook does not work at all, and the generated directory is ugly, always with 1. First, a little uncomfortable.

The trial mkdocs

$mkdocs -v mkdocs, version 1.3.0Copy the code

Mkdocs is implemented in Python and is one of the more commonly used markdown tools.

Mkdocs compatible gitbook

One of the first issues with mkDocs is how to accommodate the large number of existing Gitbook projects, and changing configurations one by one is intolerable. Looking into MkDocs, it seems that its main function is to generate static sites, not ebooks.

Fixed format mkdocs the root directory requires the mkdocs. Yml configuration file. The source files are all in the docs/ directory of the root directory and cannot be configured.

Unlike Gitbook, which requires a fixed summary.md file to represent a directory, mkdocs automatically generates a directory index based on the directory structure of docs/.

Typical gitbook multilanguage project directory:

LANGS.md
de/
  book.json
  SUMMARY.md
  README.md
en/
  book.json
  SUMMARY.md
  README.md
zh/
  book.json
  SUMMARY.md
  README.md
  GLOSSARY.md
Copy the code

Of course you can create a new docs directory and move the languages to the docs directory, but git will generate a bunch of changes that are not compatible. You can use soft links to do this:

docs/ de -> .. /de en -> .. /en zh -> .. /zhCopy the code

Use the command ln -s.. /en docs/en will do, mkdocs. Yml will do, nothing special.

Footnotes automatically generate sequences

Mkdocs itself does not support footnotes and needs to be added as an extension to the configuration file mkdocs. Yml:

markdown_extensions:
  - footnotes
Copy the code

Mkdocs automatically generates all the footnotes in a sequence of numbers starting with 1, so that the browser can recognize the jump.

Footnotes also do not support multiple lines

The mkdocs footnote does not support multiple lines, nor does it have a solution, and will display incorrectly using references.

Vocabulary is not supported

Mkdocs looks flexible and seems to require something like a preprocessor to be written in custom form without further exploration.

Build speed

Python is supposed to be faster, but benchmarking without Benchmark is inconclusive.

Cannot generate ebook format

---

The trial mdbook

It is best to use mdBook’s binary commands directly rather than install them through the package manager, which can be cumbersome

Direct installation command

Download the system package and decompress it:

The tar wget https://github.com/rust-lang/mdBook/releases/download/v0.4.17/mdbook-v0.4.17-x86_64-unknown-linux-gnu.tar.gz -zxvf mdbook-v0.4.17-x86_64-unknown- linux-GNU.tar. gz mv mdbook ~/. Local /binCopy the code

After decompressing the current directory, there is an executable file mdbook. Move it to ~/. Local /bin to reference the command directly. To install mdBook using a package manager, you need to install the Rust package manager Cargo first and then use Cargo to install mdBook.

$mdbook --version MDBook V0.4.17Copy the code

Mdbook is the closest tool to Gitbook, with almost seamless support in terms of directory structure and usage.

Mdbook compatible gitbook

Mdbook itself is not too difficult to support multilingual projects, just write a summary.md file that contains directories for each language. However, the problem is how to support the existing Gitbook project. It is trivial to write a summary. md file containing all the directories, and the summary. md file scattered in various language directories would be obsolete.

Mdbook uses SRC as the source directory by default. You can’t create SRC and move all the source directories into it. The build directory is also different.

You can only build your own projects in each language directory, which means that having book.toml in each language directory is not a problem, since each language already has its own book.json.

de/
  book.toml
en/
  book.toml
zh/
  book.toml
Copy the code

Book.toml: SRC,build-dir,build-dir

[book] Title = "Medieval History of Rome" description = "From the fifth to the sixteenth century" author =" Multilingual = true SRC = "." [build] build-dir = "_book" create-missing = falseCopy the code

At runtime, mdBook serve is executed separately in each language directory so that more complete support is already available.

Footnotes automatically generate sequences

Like mkdocs, mdBook automatically generates sequences of numbers that jump without error.

Footnotes also do not support multiple lines

The effect is the same as mkdocs

Vocabulary is not supported

You may need to write some preprocessors according to the MDBook specification, so you’ll have to dig deeper.

Build speed

Of course, it should be built fairly quickly as expected.

Unable to generate ebooks

---

In general, the current two alternative tools are not particularly easy to use, can only continue to use Gitbook, to solve the problem must go deep into gitbook source code. But has not updated for such a long time, has not seen the community open source enthusiasts continue to contribute on this basis, is someone changed no one into the main line or the source code is too large to change? No one started a new furnace club.