Live data from Hacker News

MdBook – A command line tool to create books with Markdown

rust-lang.github.io

71–80 of 123 posts

Re: MdBook – A command line tool to create books with Markdown

#71

I’ve tried MdBook, Jekyll, and MkDocs. MdBook is slick for basic projects, but I felt it was too minimalistic for me. When I dug into the source for the MdBook sites that I liked, I saw that they had extended MdBook with some custom Rust code. My recommendations are: - MkDocs: Good default choice, reasonably flexible. - Jekyll: For people who want a little more flexibility—things like landing pages, blogs, etc. - Ant…

I also recommend MkDocs.

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.

Re: MdBook – A command line tool to create books with Markdown

#72

> It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation. 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…

You know that HTML is valid in Markdown, right?

Re: MdBook – A command line tool to create books with Markdown

#73

I just wonder why Markdown (or whatever alike, I know there are alternatives superior in numerous ways) is not the default format for books, documents and everything. Some years ago I switched to Typora and discovered I hardly ever need Word/Writer for anything I write and I only use it to open documents others would send me. 90% of books I read don't look like having a serious reason for not being in the Markdown fo…

Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways.

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.

Re: MdBook – A command line tool to create books with Markdown

#74
post #63

So far, in this thread (in no particular order): - [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/ ) - [Next…

Nice list! I've also used [nimibook](https://pietroppeter.github.io/nimibook/).

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

Re: MdBook – A command line tool to create books with Markdown

#75

Why? I'm mystified as to why there are vanishingly few VIEWERS for Markdown. One open-source project after another offers up .md files for documentation, but have you ever tried to find a plain VIEWER for Markdown?

vscode has one built in

  ctrl + shift + v

Re: MdBook – A command line tool to create books with Markdown

#76
post #50

I’ve tried MdBook, Jekyll, and MkDocs. MdBook is slick for basic projects, but I felt it was too minimalistic for me. When I dug into the source for the MdBook sites that I liked, I saw that they had extended MdBook with some custom Rust code. My recommendations are: - MkDocs: Good default choice, reasonably flexible. - Jekyll: For people who want a little more flexibility—things like landing pages, blogs, etc. - Ant…

I'm a huge user of mkdocs and totally love it. 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).

> I've trying also bookstack and even it's more "wiki" like it's great too for less tech-savvy people

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.

Re: MdBook – A command line tool to create books with Markdown

#77

I just wonder why Markdown (or whatever alike, I know there are alternatives superior in numerous ways) is not the default format for books, documents and everything. Some years ago I switched to Typora and discovered I hardly ever need Word/Writer for anything I write and I only use it to open documents others would send me. 90% of books I read don't look like having a serious reason for not being in the Markdown fo…

Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways. 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 d…

> Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways.

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.” ©

Re: MdBook – A command line tool to create books with Markdown

#78

> It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation. 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…

You know that HTML is valid in Markdown, right?

[deleted]

Re: MdBook – A command line tool to create books with Markdown

#79

Earlier quoted context omitted.

Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways. 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 d…

> Markdown is a really poor storage format. There is quasi-official standard (CommonMark), but since it's feature-poor, people mostly use something else, like GitHub Markdown. Individual apps often extend Markdown in various incompatible ways. 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 scri…

> Without a need for software as complex and resource-hungry as a web browser engine ePub would require.

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.

Post reply on HN