Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

MdBook – A command line tool to create books with Markdown

rust-lang.github.io

Post reply on HN
Print view View original

31–40 of 123 posts

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

#31

Post by klodolph »

dcchambers wrote: post #28
klodolph wrote: post #19

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 am a long time Jekyll user and I still think it's a great tool for blogs, but by far the best SSG for documentation websites I have found is Docusaurus. ( https://docusaurus.io/ ) I resisted trying it for the longest time because I didn't want a JavaScript based tool, but I am glad I caved. It's so easy to get started, crazy fast, and the sites are absolutely beautiful out of the box yet easy to customize. The mdx…

Somehow I missed Docusaurus when I surveyed documentation generators—it looks very good!

I can understand the desire to want something not written in JavaScript, and I certainly have my own language prejudices, but when I surveyed static site generators, language choice was all over the map. Like, I was willing to wrangle Ruby installations and gems to get Jekyll working, something I have nearly no experience with.

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

#32

Post by pickledish »

Since I see a few people in these comments mourning the general dive that gitbook has taken over the last few years, you might like this, an actively-maintained fork of gitbook as it was before it got bad:

https://github.com/honkit/honkit

I don’t spent a lot of time looking at these SSGs, so this one’s still my favorite

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

#33

Post by harry8 »

valbaca wrote: post #21
harry8 wrote: post #4

Way to bury the lede. Like gitbook but Free. The rust zealotry put me right off fwiw. As it does my interest in the language itself. I wish those guys would calm down they're totally detracting from whatever the strengths of rust are with that nonsense. edit: gitbook pricing for comparison https://www.gitbook.com/pricing

What zealotry? Rust isn't mentioned until the last two points of eight: mdBook is a command line tool to create books with Markdown. It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation. - Lightweight Markdown syntax helps you focus more on your content - Integrated search support - Color syntax highlightin…

> What zealotry?

The headline has been silently edited, hence the confusion. I don't much care for silent editing for just this reason.

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

#34

Post by mraza007 »

gilmi wrote: post #30

I've written an online book with mdbook ( https://lhbg-book.link ) and it was a breeze. I believe mdbook was one of the reasons I even finished the book. 1. It's super easy to install. If you have a rust toolchain, just `cargo install mdbook` 2. One command to initialize: `mdbook init my-book` 3. One command to get immediate continuous feedback: `mdbook serve` 4. It allowed me to keep writing in my preferred environm…

I have been planning to learn haskell thanks for sharing the book

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

#36

Post by lfo »

bad_username wrote: post #35

> The options and formatting will be different for other output formats such as PDF. This is the only reference to PDF in the documentation. Is it possible to render a PDF (presuming a single file)?

They know pandoc won MD to PDF battle. https://youtu.be/3f9YvjqUTlw

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

#37

Post by metabagel »

liberty-dreamer wrote: post #26
xwowsersx wrote: post #7

Me: Are we past "x but in Rust" where Rust is a totally irrelevant internal detail I don't — nor should anyone — care about? [Checks HN]: Nope.

Well, if it is implemented in Rust, then who cares whether it works or not? It's implemented in Rust!

The good thing is you don’t have to rewrite it!

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

#38

Post by wumms »

LeonB wrote: post #25

I used to use gitbook to generate til.secretGeek.net but it got slower and slower over time, would take 45 mins to build the site… and then the parts I was using were either deprecated or made “premium” - something happened. The “enshittification” set in, basically. If there’s some nice free thing you use that’s too good to be true… wait a few years it will go to muck. I bit the bullet and wrote my own very minimal s…

> spruik

spruik

- in British English (ˈspruːɪkˈ) [Australian archaic, slang]:

to speak in public (used esp of a showman or salesman)

- in American English (ˈspruːkˈ) [Australian slang]:

to make or give a speech, esp. extensively or elaborately; spiel; orate

https://www.collinsdictionary.com/jp/dictionary/english/spru...

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

#39

Post by jonasdoesthings »

bccdee wrote: post #29
klodolph wrote: post #19

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…

Wow, what is up with the material mkdocs theme ( https://squidfunk.github.io/mkdocs-material/ )? That's an extremely spiffy landing page, especially given that it's for a theme designed for a totally separate piece of software.

mkdocs-materials is underselling itself as only a theme imo. It bundles a lot of value that mkdocs is missing out of the box as plugins and tweaks, like a good client-side search, page tags, or easy support for a lot of markdown extensions (e.g. code syntax highlighting, admonitions/callouts).

From my personal experience mkdocs+mkdocs-material is like GNU+Linux.

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

#40

Post by pietroppeter »

Md book is great! We created a Nim version to support content written with nimib (a framework to publish html pages with Nim code and its results) and it has been very useful! https://pietroppeter.github.io/nimibook/index.html

As people are sharing other SSG (I think material for MkDocs is the absolute best for documentation sites), let me share a relatively unknown one that I find very interesting: https://github.com/dmulholl/ark

I have as next project to try and port this ark to Nim/nimib (and ideally nimibook should be refactored to use it).

Post reply on HN