Switch from legacy gitbook to Rust's mdBook

[OrangeChannel]

Somewhat fixes https://github.com/Irrational-Encoding-Wizardry/guide.encode.moe/issues/60 but still missing the relevant GitHub action to build to the gh-pages branch, as I'm not exactly sure how to do this and I can't get the book to work for my repo's pages (though I can preview the files just fine). We can still use Travis as the CI tool with this.

[FichteFoll]

That must have been a lot work, so thanks a lot for that.

Before I start to review this some time over the next week(s), could you give me a summary over the effective differences between our previous gitbook instance and what mdbook can do? Do we have feature parity?

[OrangeChannel]

PROS :heavy_check_mark: :

• lightweight build process, uses a single executable, pretty fast compared to the old gitbook when using serve at least from my tests, but the pages for some reason seem to become styled after the content is loaded (MathJax builds the equations when you load the page, not before)
• proper LaTeX support via MathJax
  • follows normal TeX syntax, and doesn't have the $$ problem the KaTeX plug-in did
• better builtin themes
• direct access to the style files, really only useful if someone wants to change something (maybe because of a plugin) or add a new html class
• footnotes can now have linebreaks in them
• supports multiple footnote references (i.e. same source is used twice on a page, so you have two links to the [^2] at the bottom)
• sidebar is numbered and allows for more nesting
• allows for blank or WIP pages to be shown as unclickable in the sidebar (probably the only current way to replace section headers)
• developing plug-ins is done via the rust preprocessor api
• seems we can run an arbitrary command (i.e. a Python script) to manipulate the book too before it gets rendered: https://rust-lang.github.io/mdBook/format/config.html#provide-your-own-command
• the search bar works a bit better than the old one, doesn't bring you to a new page

CONS: :x: :

• MathJax is a bit slower than KaTeX apparently but seems to have no effect for us as we have only a few small equations per page
• no Edit this page on GitHub
• footnotes do not have the ↩ character that allows you to jump back to where the footnote was on the page
• no glossary
• no section headers on the sidebar
• theme changer doesn't let you change the font style or size
• markdown comments now render on the page, so I'm not sure if there's a changed syntax or something but I've gotten rid of / replaced the <TODO> with just TODO

Some features I've brought over or already existed on both worth mentioning:

• images weren't centered by default but I've changed that with some css
• image captions don't get displayed by default so ![this text](image.png) doesn't show anywhere I've changed the formatting so img + em css rules catches the following and shows the caption centered and under the picture. Though, the captions aren't numbered automatically like in the old plug-in.
  • The new format for captions is shown in the contributing doc
  • Actually supports non-captioned pictures better than the old one, as the plugin kinda messed with them iirc or made them just not appear
• the html custom warning/info boxes still work
• still can navigate using arrow keys
• mobile works well as the sidebar works pretty much the same where it can get hidden
• the code blocks still have the copy this code symbol at the top right
• pretty much all other markdown syntax that we were using works identically and renders the same
• the fontawesome icons still work

[FichteFoll]

Thanks again for your work on this and sorry for taking such a long time.

We now have working CI and CD again in an almost blazingly fast github action, artifact download included.

Next time, you could also push to a branch on this repo, btw. You're a collaborator for a reason. :wink: