
mdBook – A utility to create modern online books from Markdown files - karlicoss
https://github.com/rust-lang/mdBook
======
michaelangerman
For me the testament as to the quality of this product is to look at the Rust
doc ecosystem. Anyone who has read the Rust docs knows how well done the
presentation of the material is

Here is one example...

[https://doc.rust-lang.org/book/](https://doc.rust-lang.org/book/)

------
xvilka
So far the biggest missing feature is the export to PDF[1]. With projects like
crowbook[2] and Tectonic (TeX engine) oxidation[3] it can be a perfect
solution for creating modern documents without the legacy churn.

[1] [https://github.com/rust-lang/mdBook/issues/815](https://github.com/rust-
lang/mdBook/issues/815)

[2] [https://github.com/lise-henry/crowbook/](https://github.com/lise-
henry/crowbook/)

[3]
[https://github.com/crlf0710/tectonic/tree/oxidize](https://github.com/crlf0710/tectonic/tree/oxidize)

~~~
bluejekyll
Does this plugin work? [https://crates.io/crates/mdbook-
latex](https://crates.io/crates/mdbook-latex)

The features list looks like there's some gaps, but probably worth checking
out.

------
n8henrie
I live in a very rural town with poor internet and kept wanting a good way to
make an offline ebook from these mdbook sites (to them turn to mobi with
calibre for my kindle).

For a while I struggled using a recursive wget on the `print` page and using
calibre's `ebook-convert`.

Last week I finally found [mdbook-epub][0] which seems to do a fine job! The
standalone binary choked on some codeblocks, but using it as a plugin worked
great.

[0]: [https://github.com/Michael-F-Bryan/mdbook-
epub/blob/master/R...](https://github.com/Michael-F-Bryan/mdbook-
epub/blob/master/README.md)

------
bluejekyll
mdbook is one of the tools I have grown to use and love so much. One of the
things I love about it is that the toolchain for building and using it is just
the Rust standard toolchain, which means no crazy dependency hell to manage.
By comparison I’ve found Jekyll to be a long-term annoyance to keep up-to-
date, I’m probably using it wrong. I know.

Anyway, beyond that, it’s one of the few Rust tools that I’ve gotten decent
adoption of at work, due to its simple nature.

Just wanted to say nice work to everyone who’s contributed to the project.

~~~
mrec
For using it on Win/Mac/Linux you don't even need the Rust standard toolchain;
just download the standalone executable. No runtime, no npm, sheer bliss.

------
ipnon
From a theoretical perspective, it would be nicer to have a "programming"
language for writing modern, online books than to have a Markdown compiler for
the same purpose, because Markdown is not a programming language. Markdown has
no authoritative definition. It's more like a family of similar HTML macro
collections.

~~~
the_pwner224
I recently switched from Markdown to AsciiDoc. It is much better in my
opinion. The syntax is similar enough to MD that just having the adoc
cheatsheet bookmarked is enough to switch. But it's more structured, much more
fully featured, just two big implementations (AsciiDoc and AsciiDoctor) which
are largely compatible. There's only one way to mark the language of a code
block, only one way to make lists, only one way to make footnotes, etc. Also
it actually has first-class support for things like footnotes and
admonitions[0] etc.

It is a syntactic sugar layer on the DocBook XML format which is apparently
used to make actual books. But AsciiDoctor compiles it to everything from
DocBook XML to HTML to Markdown to ePub to PDF.

Another thing I like is that AsciiDoctor actually comes with a good default
stylesheet. If you just turn MD into HTML you get ugly garbage and need to
figure out how to put CSS into the HTML etc. AsciiDoctor has a good default
theme as well as a number of other themes available[1], and by default will
embed the CSS into the HTML so you just have one file to distribute. It even
shows anchor links to the headings when you hover over them.

[0]: [https://asciidoctor.org/docs/asciidoc-writers-
guide/#admonit...](https://asciidoctor.org/docs/asciidoc-writers-
guide/#admonitions)

[1]: this made it easier for me to add the themes, and includes more beyond
the ones bundled with adoc: [https://github.com/darshandsoni/asciidoctor-
skins](https://github.com/darshandsoni/asciidoctor-skins)

------
imroot
I use softcover for this:

* [https://github.com/softcover/softcover](https://github.com/softcover/softcover)

One of the things that I like about Softcover is that it will also build .mobi
and .epub formats, so I can give developers (via our MDM system) copies of
runbooks, and then revoke those copies once they leave our employer.

~~~
616c
That's a really neat concept, thank you.

------
taftster
Is there any comparison of mdBook to AsciiDoc? It seems the SUMMARY.md page of
mdBook is critical to promote markdown effectively into a "book" presentation,
something that feels more like on addon specification to markdown that is
already handled in asciidoc? What advantage does mdBook give you then?

~~~
steveklabnik
It is sort of comparing apples to oranges. AsciiDoc is a markup language for
documentation. mdBook is a tool that uses the Markdown markup language, and
adds a bit of structure so that you get something that appears coherent.

> What advantage does mdBook give you then?

If you prefer Markdown to Asciidoc, then mdBook would be a better fit.

------
atrilumen
Is it still connecting to Google Fonts?

Open Issue:

Remove Google surveillance #847

[https://github.com/rust-lang/mdBook/issues/847](https://github.com/rust-
lang/mdBook/issues/847)

~~~
steveklabnik
By default, yes. Anyone can fix that in their books in the meantime by
generating the theme and then deleting some lines.

It is tough to get contributors and maintainers of projects like this, and
this issue in particular has been bombed by folks who don't even use Rust and
are acting like the sky is falling. It's incredibly demotivating.

~~~
wccrawford
I wish people in general could get used to the idea that not everything is
designed with them in mind, and they might not be the intended audience.

If privacy is your number one priority and you absolutely can't have Google
"spying" on you, then a lot of software and websites probably just aren't for
you.

Instead, they bombard people who are doing great things for free, making them
make little changes to please them instead of great changes that could please
most people.

I'd be less critical of them if they were submitting PRs instead of just bug
reports.

~~~
Arnavion
>I'd be less critical of them if they were submitting PRs instead of just bug
reports.

So, exactly what the author of that issue did on the same day they made the
issue.

~~~
wccrawford
So, they _did_ submit a PR (which is great!), but it wasn't acceptable to the
maintainer. Other things were suggested, but none of the PRs met the
requirements, and so none were accepted.

------
saurabhnanda
Is there a link to sample books rendered using this tool? Did I miss it in the
README?

~~~
karlicoss
Right in the beginning of readme! :) [https://github.com/rust-
lang/mdBook#what-does-it-look-like](https://github.com/rust-lang/mdBook#what-
does-it-look-like)

There is also a collection of mdbooks by other people
[https://github.com/softprops/awesome-
mdbook](https://github.com/softprops/awesome-mdbook)

And a shameless plug, I'm using mdbook to publish my org-mode notes
[https://beepb00p.xyz/exobrain/](https://beepb00p.xyz/exobrain/)

------
dhbradshaw
I've been using mdBook for awhile to keep a personal journal and also
separately to keep a work log.

I really like being able to keep notes in Markdown tracked in git and at the
same time being able to view and search through those notes in the form of a
nice looking web book.

~~~
Poems
That's really interesting, do you mind sharing how you set it up for notes and
a work log?

~~~
dhbradshaw
I leave it in standard configuration, but fill in Summary.md by adding new
content to the top. That way when I open it I see the most recent notes first.

I have a shell script that opens vscode and starts mdbook. For my journal the
script also checks to see if there's an entry for today. If there isn't, it
will add one to the top of Summary.md, which then creates a new file for me to
write in for that day. In the meantime mdbook has opened up the book for me to
look at that side.

When I open the book I see what I wrote more recently and can also go back to
documents from the past.

------
dchuk
What’s my best option if I want to write an online book in this style but from
an IPad? It seems like I’m stuck using something like Ulysses and the setting
up a tool chain on a VPS or something... anyone have any tips?

~~~
karlicoss
Not sure what's Ulysses, but you could probably set a Github action for it?
This way it would be rebuilt and deployed on pushing into your git repository
(hopefully it's possible to work with git from an ipad?)

[https://github.com/peaceiris/actions-
mdbook](https://github.com/peaceiris/actions-mdbook)

~~~
Jtsummers
It is possible to work with git from an iPad. I've set up a similar workflow
(not for mdBook but for gitbook) a long time ago. I used Working Copy and
Textastic.

------
ollerac
This looks really nice on mobile and the default typography is great. I've
been looking for something like this for a while to publish a few short non-
technical books I've been working on.

I'll definitely give it a try!

------
karmakaze
Are there any plans to add more interactive features, or is the expected use
more static? e.g.

    
    
      - Tabs
      - Variants (like language selection)
    

If it already has these, awesome!

------
marvindanig
ack, no. online websites, files and webpages. going by the strict definition
of a book none of those online things are books though.

------
bachmeier
"Create book from markdown files. Like Gitbook but implemented in Rust"

Now that's one hell of a good reason to use it. It's reimplements existing
functionality in Rust!

~~~
karlicoss
Perhaps the readme should emphasise it, but the gitbook public repository was
abandoned by the company who open sourced it.

~~~
steveklabnik
I actually did not know this until this comment.

mdbook was originally created because we liked the UX of gitbook, but didn't
want to introduce a Node dependency into building Rust.

~~~
bachmeier
That would certainly be useful information to provide in the readme. I'd never
heard of gitbook or mdbook before this.

