[HN Gopher] mdBook - A utility to create modern online books fro...
___________________________________________________________________
mdBook - A utility to create modern online books from Markdown
files
Author : karlicoss
Score : 203 points
Date : 2020-04-13 09:18 UTC (13 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| ipnon wrote:
| 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.
| gyrgtyn wrote:
| https://docs.racket-lang.org/pollen/ "Pollen: the book is a
| program"
| searchableguy wrote:
| What do you think of https://mdxjs.com ?
| the_pwner224 wrote:
| 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...
|
| [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
| imroot wrote:
| I use softcover for this:
|
| * 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.
| dhbradshaw wrote:
| 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.
| bluejekyll wrote:
| 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 wrote:
| 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.
| marvindanig wrote:
| ack, no. online websites, files and webpages. going by the strict
| definition of a book none of those online things are books
| though.
| bachmeier wrote:
| "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!
| [deleted]
| karlicoss wrote:
| Perhaps the readme should emphasise it, but the gitbook public
| repository was abandoned by the company who open sourced it.
| steveklabnik wrote:
| 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 wrote:
| That would certainly be useful information to provide in
| the readme. I'd never heard of gitbook or mdbook before
| this.
| red_admiral wrote:
| 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.
| michaelangerman wrote:
| 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/
| ollerac wrote:
| 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!
| xvilka wrote:
| 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
|
| [2] https://github.com/lise-henry/crowbook/
|
| [3] https://github.com/crlf0710/tectonic/tree/oxidize
| bluejekyll wrote:
| Does this plugin work? https://crates.io/crates/mdbook-latex
|
| The features list looks like there's some gaps, but probably
| worth checking out.
| atrilumen wrote:
| Is it still connecting to Google Fonts?
|
| Open Issue:
|
| Remove Google surveillance #847
|
| https://github.com/rust-lang/mdBook/issues/847
| steveklabnik wrote:
| 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 wrote:
| 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 wrote:
| >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 wrote:
| 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.
| shadowoflight wrote:
| > 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.
| Arnavion wrote:
| >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.
| steveklabnik wrote:
| > 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?
| Arnavion wrote:
| 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.
| saurabhnanda wrote:
| Is there a link to sample books rendered using this tool? Did I
| miss it in the README?
| karlicoss wrote:
| Right in the beginning of readme! :) 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
|
| And a shameless plug, I'm using mdbook to publish my org-mode
| notes https://beepb00p.xyz/exobrain/
| taftster wrote:
| 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 wrote:
| 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.
| dchuk wrote:
| 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?
| Tagbert wrote:
| I've heard good things about IA Writer
| https://thesweetsetup.com/apps/our-favorite-markdown-writing...
| karlicoss wrote:
| 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
| Jtsummers wrote:
| 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.
| [deleted]
___________________________________________________________________
(page generated 2020-04-13 23:00 UTC)