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

81–90 of 123 posts

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

#81

Post by d4rkp4ttern »

msravi wrote: 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…

HackMD is often my go-to to create a shareable (and collaboratively editable) markdown document that supports math notation.

https://hackmd.io/

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

#82

Post by still_grokking »

Tangent question: What are currently viable Markdown alternatives?

Imho Markdown is a overall terrible and (especially regarding technical writing!) very limited format. But nothing else seems popular. Why actually?

Are there any realistic alternatives?

Thanks for some hints!

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

#83

Post by dylanowen »

frafra wrote: post #59
dylanowen wrote: post #18

I love MdBook. It's also dirt simple to customize it with plugins or rendering backends: * https://github.com/dylanowen/mdbook-graphviz * https://github.com/dylanowen/mdbook-confluence

You might be interested in https://kroki.io and https://github.com/JoelCourtney/mdbook-kroki-preprocessor .

Oh nice! This has so many great diagramming tools I'm now learning about.

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

#84

Post by d4rkp4ttern »

jonasdoesthings wrote: post #39
bccdee wrote: post #29

Earlier quoted context omitted.

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.

At least for Python documentation, this plus mkdocstrings is great.

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

#85

Post by d4rkp4ttern »

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.

Check out the Pydantic docs pages - they use Mkdocs-material

https://docs.pydantic.dev/latest/

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

#87

Post by tpreetham »

still_grokking wrote: post #82

Tangent question: What are currently viable Markdown alternatives? Imho Markdown is a overall terrible and (especially regarding technical writing!) very limited format. But nothing else seems popular. Why actually? Are there any realistic alternatives? Thanks for some hints!

org-mode is a brilliant format. The limitation is that you would have to use Emacs or something which support .org files.

https://youtube.com/playlist?list=PLVtKhBrRV_ZkPnBtt_TD1Cs9P...

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

#88

Post by letmeinhere »

still_grokking wrote: post #82

Tangent question: What are currently viable Markdown alternatives? Imho Markdown is a overall terrible and (especially regarding technical writing!) very limited format. But nothing else seems popular. Why actually? Are there any realistic alternatives? Thanks for some hints!

AsciiDoc, org-mode, ReStructured Text are some of the other light markup contenders

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

#90

Post by still_grokking »

tpreetham wrote: post #87
still_grokking wrote: post #82

Tangent question: What are currently viable Markdown alternatives? Imho Markdown is a overall terrible and (especially regarding technical writing!) very limited format. But nothing else seems popular. Why actually? Are there any realistic alternatives? Thanks for some hints!

org-mode is a brilliant format. The limitation is that you would have to use Emacs or something which support .org files. https://youtube.com/playlist?list=PLVtKhBrRV_ZkPnBtt_TD1Cs9P...

What else besides EMACS supports .org files?

Form the alternatives I've seen so far it looks best. But EMACS? (I'm on Linux, but never liked EMACS or Vi(m)).

The second best looking alternative seems AsciiDoc. It has some more tooling as I see it.

But really like the .org syntax best so far. So any recommendations for tooling?

Post reply on HN