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
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.
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.
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.
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.
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.
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.
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?
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.
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.
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.
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.
> I'd be less critical of them if they were submitting PRs instead of just bug reports.
See, this is what's bizarre to me about this particular problem - the kind of people who (1) worry about these types of things and (2) are running CLI software from Github should be capable of figuring out how to implement the feature(s) they want and submit pull requests instead of opening issues. This is FOSS software, the price of entry is $0, so I don't get how people think they're entitled to any particular feature without implementing it themselves, especially features as marginally-useful as not requesting fonts from Google.
>It is tough to get contributors and maintainers of projects like this, [...]
It has had a PR since day one, from the same person that opened the issue.
>[...] 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 has been "bombed" by people who use mdBook, or rather who no longer use mdBook because they were affected by the issue in question. The issue is on rust-lang/mdBook, not rust-lang/rust, and I don't see anywhere in its README.md that says you need to be a Rust user to use mdBook.
> It has had a PR since day one, from the same person that opened the issue.
Absolutely, and I'm appreciative of that. As you can see from that PR, it is unclear what the procedure is to get said PR merged; there's assertions that this is breaking, and assertions that it is not. This conversation was continued in the issue, and the PR author did not respond. It's effectively in a holding pattern where nobody has responded to the maintainer's feedback about the PR, either by updating the original PR or opening a new one.
Part of why this has taken a while is that mdbook has not had particularly strong leadership over its existence, due to what I said. The original author wrote enough for his purposes, I tweaked stuff for my purposes, but it's never been anyone's specific focus. There have been periods with effectively no maintenance. That's how open source goes.
> It has been "bombed" by people who use mdBook, ... I don't see anywhere in its README.md that says you need to be a Rust user to use mdBook.
To be clear, I do not think everyone in this issue is from some sort of "outside." But there's at least one person in that thread who started on it immediately after publicly trashing Rust. He then continues to be abrasive on the issue.
This contributes to a lack of bandwidth, at least for me. I'm not gonna bother touching this PR when there is so much other work to do, and I don't have to deal with this kind of thing. (I am also not the primary maintainer of mdbook so I don't know how the actual maintainers feel about it, maybe they aren't affected by it in the same way.)
I expect that someday, this will get sorted out, if the folks who care so much actually put in the effort to make the changes happen. Or maybe they'll use another tool. I think that's also totally fine. This was part of a broader move to remove google fonts across Rust properties, most of them were taken care of, because folks pushed and got the work done. I think this might be the last bit?
I understand your lack of motivation to fix the issue, and have been in a similar boat in some of my own personal projects.
>To be clear, I do not think everyone in this issue is from some sort of "outside." But there's at least one person in that thread who started on it immediately after publicly trashing Rust. He then continues to be abrasive on the issue.
Ah, I thought you meant "folks" to mean everyone posting on the issue / upvoting the OP. Thank you for clarifying. Assuming you're talking about who I think you're talking about, I can understand your position.
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.
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.
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.
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?
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?)
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.
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.
And, annoyingly, a lot of google searches for "gitbook xyz" just turn up the new cloud-hosted gitbook subscription service. You have to go through archive.org or similar to read the documentation for the original.
I just started using GitBook for a blog because it is opensource and offers a free hosted site.
As I understand it only the CLI portion is unmaintained[0] which aligns with how it's being used by the developers (and me). [Btw, the older version is easily found as GitBook legacy.]
Here is one example...
https://doc.rust-lang.org/book/