MdBook – A command line tool to create books with Markdown
rust-lang.github.io
rust-lang.github.io
…but it’s not the only bummer. The usage of Highlight.js + MathJax on the front-end is horribly wasteful. Why? It demands all clients parse & render the syntax/LaTeX which is not only taxing on CPUs and batteries, but this action is idempotent meaning every user agent on every page visit is going to do the same wasteful parsing to get the same result. There is no good reason that syntax highlighting shouldn’t be done at build time nor should it require JavaScript.
Seems a bit strange. I wonder why they chose to use a CDN for that one js file.
Perhaps because MathJax support is optional? https://rust-lang.github.io/mdBook/format/mathjax.html
Even though the MathJax js file will in turn probably load more things hosted on the CDN. I don’t understand why they are not putting all of the MathJax files alongside the generated HTML files. So that one does not have to rely on any CDN.
That’s usually why people use CDNs. It’s more important for MathJax than, say, interactive scripts, since it can cause rendering.
I don’t think MathJax loads any additional files (I don’t remember seeing any additional network requests).
- [Jekyll](https://jekyllrb.com/)
- [Hugo Book](https://github.com/alex-shpak/hugo-book)
- [MdBook](https://rust-lang.github.io/mdBook/)
- [MkDocs](https://www.mkdocs.org/)
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)
- [GitBook](https://www.gitbook.com/)
- [Antora](https://antora.org/)
- [Docusaurus](https://docusaurus.io/)
- [Nextra](https://nextra.site/)
- [Astro](https://astro.build/)
- [Starlight](https://starlight.astro.build/)
- [Clowncar](https://github.com/secretGeek/clowncar)
- [Keenwrite](https://github.com/DaveJarvis/keenwrite)
- [Quarto](https://quarto.org/)
- [Honkit](https://github.com/honkit/honkit)
- [JupyterBook](https://jupyterbook.org/)
(nb) I collaborate on Jupyter Book
Its a port of mdbook to Nim, but also extends it with the ability to generate interactive content as well using Nim's Javascript backend. Though I haven't tried this piece myself I like the idea of an all in one way to make interactive elements when desired: https://pietroppeter.github.io/nimib/interactivity.html
Happy user here.
Which ones have...?
- search built in
- PDF output
- ePub output
- more than one theme
- lots of other stuffIt's a hosted SaaS, so it's technically not a static-site generator, but it's an alternative to the above.
My recommendations are:
- MkDocs: Good default choice, reasonably flexible.
- Jekyll: For people who want a little more flexibility—things like landing pages, blogs, etc.
- Antora: For people who want the best docs, and are willing to put in the most effort. It will manage, for you, the process of generating documentation sites that collect documentation from multiple projects and possibly multiple versions of each project. Asciidoc is full of features you’ll find useful.
Hugo looks like it has a lot of flexibility like Jekyll, but it seems to take more effort to get everything working the way you want, and it also seems like there’s just too much variation in how the different themes work. To be honest, I never really managed to make anything with it—I found out that the theme I was using didn’t have some features I wanted, so I switched to a different theme, but it’s not easy to switch themes. I was too frustrated and gave up.
It looks like MdBook is reasonably active, so I’m sure it will catch up.
I resisted trying it for the longest time because I didn't want a JavaScript based tool, but I am glad I caved. It's so easy to get started, crazy fast, and the sites are absolutely beautiful out of the box yet easy to customize. The mdx support is awesome too.
I can understand the desire to want something not written in JavaScript, and I certainly have my own language prejudices, but when I surveyed static site generators, language choice was all over the map. Like, I was willing to wrangle Ruby installations and gems to get Jekyll working, something I have nearly no experience with.
From my personal experience mkdocs+mkdocs-material is like GNU+Linux.
I've trying also bookstack and even it's more "wiki" like it's great too for less tech-savvy people (I usually edit my mkdocs projects in vscode and keet them in git repos and bookstack is all web based).
Thanks! My main goal when building BookStack was to build a platform that could be used by all departments, of varying technical confidence, of the company that I was working at since existing open source documentation/wiki systems were positioned for a more technical audience.
It was the most painless experience I've had with quickly setting up docs from a bunch of .md files, and the plugins give it enough flexibility for most of the usual stuff I need.
I bit the bullet and wrote my own very minimal static site generator in .net, so the site builds in a few seconds again. Note that I’m not spruiking it for others to use… because if it became popular, no doubt I’d end up enshittifying it too.
spruik
- in British English (ˈspruːɪkˈ) [Australian archaic, slang]:
to speak in public (used esp of a showman or salesman)
- in American English (ˈspruːkˈ) [Australian slang]:
to make or give a speech, esp. extensively or elaborately; spiel; orate
https://www.collinsdictionary.com/jp/dictionary/english/spru...
One example, I really like the page TOC on the right side that is notably absent from mdbook, where it seems the standard to set up SUMMARY very detailed and break what could've been a single page into many different files.
It also gives a nice toc/tags on the right side (if you want it), and the ability to split the page into columns. The katex support is good (looks like mdBook uses mathjax) and publishing is easy and is just a push/rsync.
I’m extremely satisfied with 80-90% of the standard Gitbook markdown flavor. Then every now and then I really wanna make a complicated table, or a code block highlighting few lines while maintaining syntax highlighting, or an interactive slider, or a formula calculator that’s built-in the documentation instead of a complicated function, or a particular graph/chart etc. I don’t know how something like mdx would work for a large team (ever tried to clone Microsoft’s doc repo?) but at least for my own stuff, it seems like a definite improvement.
First time I heard of .mdx and looked up the site [0]. I am insufficiently in the loop of frontend standardization. Now it would be great to get rid of flavors and have one universal approach. In the Docs I read:
> MDX is not coupled to React. You can also use it with Preact, Vue, Emotion, Theme UI, etc. Both the classic and automatic JSX runtimes are supported.
A sibling comment already mentions a Svelte implementation [1]. So I fail to see how this doesn't open a pandora's box of yet more flavors, this time coupled to frontend frameworks. First in .mdx and then incompatible with .md
Extensibility. Yes, I guess, if your stack is supported by any of the existing implementations.
I cannot see how this yields maintainable source. Sure, spaghetti code is nice for quick, one off scripts, but if you'd volunteer for helpdesk shift to be yelled at rather than fix a bug in 5k SLOC collection of Windows Batch scripts, then maybe you should reconsider mdx.
* https://github.com/DaveJarvis/keenwrite
For example:
java -jar keenwrite.jar \
--all \
--r-dir=$PWD/bin \
--r-script=$PWD/bin/editor.R \
--image-dir=$PWD/images \
--variables=$PWD/variables.yaml \
--theme-dir=$HOME/dev/java/keenwrite/themes/boschet \
--metadata=title={{book.title}} \
--metadata=byline={{book.author.byline}} \
--metadata=keywords={{book.keywords}} \
--metadata=copyright={{book.copyright}} \
--metadata="reviewer=$1 $2, $3" \
--chapters="-14" \
--input="$PWD/chapter/01.Rmd" \
--output="${TEMP_NAME}"
Some sample outputs:
* https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...
I write a lot of documentation as part of my job and having Markdown side by side with the rendered output is great. Once you get the hang of the syntax, markdown is so much faster to write than using any text editor like Word. Just writing a list in text editors is painful.
There are better alternatives (e.g. AsciiDoc, but it's specialized towards documentation), but they don't have anything close to the momentum of Markdown.
> 90% of books I read don't look like having a serious reason for not being in the Markdown format either.
Markdown is a late comer to the game, so the better question is - why should books be in Markdown? Markdown's biggest (or the only?) advantage compared to binary/XML based formats is sort-of readability in plain text, but that's just not that important for the majority of publishers and readers.
I hope GitHub and Obsidian are going to synchronise their MarkDown extensions in near future and this will become The Standard. Whatever a case, anybody can easily write a script to automatically convert any Markdown flavour to another.
> why should books be in Markdown? Markdown's biggest (or the only?) advantage compared to binary/XML based formats is sort-of readability in plain text, but that's just not that important for the majority of publishers and readers.
Read anywhere. I mean anywhere. Without a need for software as complex and resource-hungry as a web browser engine ePub would require. I used to read TXT books on a pocket MP3 player during the pre-Android era. Also very easy automated processing.
In fact my actual preferred format for books is FB2. I mostly convert ePub books to FB2 to read on a PocketBook eInk device because it would use book-specified fonts and pages (which I never want) if I don't and FB2 is sort-of Markdown-like (in terms of its logic and features) XML. FB2 also has a great metadata section to store information about the book.
And besides books there also are documets. Word/LibreOffice documents others would send me often are real pain to modify as WYSIWYG word processors bundle tons of redundant invisible formatting details for every bit of text even when not asked for.
“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.” ©
I know that technology purists love that, but any electronic reading device handles HTML easily (especially the simple HTML in ePubs).
The point becomes moot when your book contains images/illustrations and you (like a normal reader) want to view them within the content. You will use some Markdown formatter/viewer which is again based on browser.
> Word/LibreOffice documents others would send me often are real pain to modify as WYSIWYG word processors bundle tons of redundant invisible formatting details for every bit of text even when not asked for.
Markdown is just insufficient for any non-trivial document. There isn't any standard way to set image size for example. There's no standard way to create even rudimentary tables.
> “Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”
Then go for plain text. All those headings and asterisks are a distraction anyway. Years ago, many e-books used to be distributed in plain text in fact.
Markdown is more semantic. E.g. it gives you a ToC (a very important feature of a good book, and it has to be semantic markup-based when you decouple the text from the view by omitting explicit pagination) for free.
This is also a very classic "well I could do it better" engineer trap so please don't assume that without some research. It's an ancient domain relative to what we're talking about here and has accumulated a lot of valuable insight & technique that should not be simply discarded because markdown is almost good enough for some things.
Most professionals use expensive professional software for it. Latex or pollen or other pure markup solutions only work for smallish documents, or digital ones. Once you're going to print, esp in different formats, you need to care about page imposition, aligning with folios & signatures, widows & orphans etc. Just generally the physical reality of paper leaking into your abstraction of "the book" in ways markup alone can't accommodate.
[0] https://github.com/learnbyexample/scripting_course#ebooks
Imho Markdown is a overall terrible and (especially regarding technical writing!) very limited format. But nothing else seems popular. Why actually?
Are there any realistic alternatives?
Thanks for some hints!
https://youtube.com/playlist?list=PLVtKhBrRV_ZkPnBtt_TD1Cs9P...
Form the alternatives I've seen so far it looks best. But EMACS? (I'm on Linux, but never liked EMACS or Vi(m)).
The second best looking alternative seems AsciiDoc. It has some more tooling as I see it.
But really like the .org syntax best so far. So any recommendations for tooling?
Does Markdown have footnotes or endnotes? No?
People are still misusing it for everything! Especially for technical writing, which is just nuts.
I think markdown's popularity comes from its simplicity. For things like bulleted lists, especially nested ones, I can just type an asterisk and keep going. The raw input is still very readable (for the most part) and adding formatting is quick and easy. For anything basic - such as chat systems, social media posts/comments, or quick note systems - I don't think anything more is needed.
Something like reStructuredText (.rst) is a similar alternative, but I think that if you're irritated by the limits of Markdown then rST isn't going to be any better. If you really want good formatting options, then LaTeX is the best I can think of at the moment.
If you aren't trying to build a SPA or something like that and you just want to mark up some text for formatted output ... HTML is kinda made for that task.
That being said, I tend to stick with Markdown since I find angle bracket tags to be noisy and distracting when I view documents in plain text.
It’s just plain old dumb boring static text that is being moved around the web.
The internet was essentially created so that CERN could share plain old text documents with others remotely.
Why do I need a big bloated overly complicated PHP webserver that talks to an overly complicated database, when it’s just plain old static text after all?
Personally I'm happy for it because it'll finally stop programming languages from inventing their own domain-specific oddly-syntaxed subset of HTML; the way Rust uses it is something others have no reason not to copy. For your own technical writing, AsciiDoc works pretty well.
[1]: https://starlight.astro.build/
[2]: https://astro.build/
Like gitbook but Free.
The rust zealotry put me right off fwiw. As it does my interest in the language itself. I wish those guys would calm down they're totally detracting from whatever the strengths of rust are with that nonsense.
edit: gitbook pricing for comparison https://www.gitbook.com/pricing
> Automated testing of Rust code samples
> mdBook is used by the Rust programming language project, and The Rust Programming Language book is another fine example of mdBook in action.
mdBook is a command line tool to create books with Markdown. It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation.
- Lightweight Markdown syntax helps you focus more on your content - Integrated search support - Color syntax highlighting for code blocks for many different languages - Theme files allow customizing the formatting of the output - Preprocessors can provide extensions for custom syntax and modifying content - Backends can render the output to multiple formats - Written in Rust for speed, safety, and simplicity - Automated testing of Rust code samples
It mentions Rust because it's written in Rust and used by the Rust project.
In other words, the project wouldn't exist without Rust but
The headline has been silently edited, hence the confusion. I don't much care for silent editing for just this reason.
1. It's super easy to install. If you have a rust toolchain, just `cargo install mdbook`
2. One command to initialize: `mdbook init my-book`
3. One command to get immediate continuous feedback: `mdbook serve`
4. It allowed me to keep writing in my preferred environment (emacs)
5. It looked good by default. I could focus on the content.
6. Setting up auto deploy ci on github is about 30 lines for yaml
Though one point of improvement would be better support for other export formats such as pdf and epub.
tl;dr mdbook allowed me to use the path of least resistence to complete my project, and I highly recommend it.
Also it is possible other platforms can do the same or better but I haven't tried them.
As people are sharing other SSG (I think material for MkDocs is the absolute best for documentation sites), let me share a relatively unknown one that I find very interesting: https://github.com/dmulholl/ark
I have as next project to try and port this ark to Nim/nimib (and ideally nimibook should be refactored to use it).
I maintain a simple knowledge base for myself https://til-mraza007.vercel.app/
I love how simple it is
https://github.com/honkit/honkit
I don’t spent a lot of time looking at these SSGs, so this one’s still my favorite
Markdown is really crap for any of that.
Any real writer knows that the best way to communicate an idea quickly and effectively is to present it the right way. Markdown does not have good presentation. It was not designed for good presentation. It was designed to write an incredibly basic-looking document, such that the plaintext and rendered document look similar.
I know this is going to be a shock to everyone. But it turns out that ASCII isn't the best way to encode presentation. On behalf of the poor SOBs that have to read what you churn out: Please stop subjecting people to your shitty presentation and get a real document format. Thanks.
##### This
* is not a
* definition list
I would love to not use a browser engine at all (and moderately detest Mermaid because it cannot work fully in-memory without instantiating one), but it works.
Docusaurus is an amazing tool for startups, but it started to show its weaknesses as we tried to scale it.
Our project requirements needed something more, so I ended up forking Docusaurus and started working on my own free open-source solution.
Check it out, I’d love to hear what everyone thinks! :)
Mkdocs is more flexible, has more themes, better ecosystem. Mdbook has better defaults, easier deployment, is more standard across rust projects
Recommend using the material design theme for MkDocs as a starting point. If you are working on a Rust project, use MdBook instead. If you have lots of docs / multiple projects / multiple versions, use Antora. If you want cooler landing pages, use Jekyll.
ctrl + shift + vJust a lightweight viewer.
This is the only reference to PDF in the documentation. Is it possible to render a PDF (presuming a single file)?
[Checks HN]: Nope.
Oh. and it's free.