mdBook – A utility to create modern online books from Markdown files
github.com
github.com
Here is one example...
[1] https://github.com/rust-lang/mdBook/issues/815
The features list looks like there's some gaps, but probably worth checking out.
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...
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.
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...
[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
> What advantage does mdBook give you then?
If you prefer Markdown to Asciidoc, then mdBook would be a better fit.
Open Issue:
Remove Google surveillance #847
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.
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.
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.
So, exactly what the author of that issue did on the same day they made the issue.
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.
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?
>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.
* 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.
There is also a collection of mdbooks by other people https://github.com/softprops/awesome-mdbook
And a shameless plug, I'm using mdbook to publish my org-mode notes https://beepb00p.xyz/exobrain/
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 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.
I'll definitely give it a try!
- Tabs
- Variants (like language selection)
If it already has these, awesome!Now that's one hell of a good reason to use it. It's reimplements existing functionality in Rust!
mdbook was originally created because we liked the UX of gitbook, but didn't want to introduce a Node dependency into building Rust.
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.]
[0] https://github.com/GitbookIO/gitbook#%EF%B8%8F-deprecation-w...