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

111–120 of 123 posts

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

#111

Post by gglitch »

giraffe_lady wrote: post #97
qwerty456127 wrote: post #65

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…

There is a lot of nuance and complication to typesetting books that isn't apparent to an untrained observer, and markdown + css simply isn't sophisticated enough to handle it. Even html/css + js is technically capable but far far behind the state of the art in digital typesetting. This is also a very classic "well I could do it better" engineer trap so please don't assume that without some research. It's an ancient d…

Do you have recommendations? (La)TeX, maybe, or *roff?

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

#112

Post by BenFeldman1930 »

still_grokking wrote: post #90
tpreetham wrote: post #87

Earlier quoted context omitted.

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?

AsciiDoc still has no footnotes, but only endnotes. Therefore not really useful for writing non-fiction books. As org-mode files are only text files, you can use any editor you like. If you want all the goodies (agenda, TODOs etc), you have to use Emacs, yes.

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

#113

Post by toastal »

singhrac wrote: post #105
codetrotter wrote: post #55

Earlier quoted context omitted.

Looks like MathJax is hosted on a CDN. Everything else, from css to other js files, is hosted alongside the HTML files. Seems a bit strange. I wonder why they chose to use a CDN for that one js file. Perhaps because MathJax support is optional? https://rust-lang.github.io/mdBook/format/mathjax.html Even though the MathJax js file will in turn probably load more things hosted on the CDN. I don’t understand why they ar…

Maybe it’s because MathJax loading slow would delay rendering, and using a CDN-hosted MathJax increases the chance the content is cached? That’s usually why people use CDNs. It’s more important for MathJax than, say, interactive scripts, since it can cause rendering. I don’t think MathJax loads any additional files (I don’t remember seeing any additional network requests).

With first-party isolation being the standard for the last couple of years, there are no “shared caches”. A third-party CDNs might load a particular resource faster, but at the cost of user privacy & reliability. You can know, barring exceptional circumstances, that if your site loaded, it can load its own libraries. Look at the news of Cloudflare, Fastly, et al. going down and the ‘internet breaking’ because there’s been too much centralization and bad advice that all site’s need these sorts of ‘optimizations’.

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

#114

Post by giraffe_lady »

gglitch wrote: post #111
giraffe_lady wrote: post #97

Earlier quoted context omitted.

There is a lot of nuance and complication to typesetting books that isn't apparent to an untrained observer, and markdown + css simply isn't sophisticated enough to handle it. Even html/css + js is technically capable but far far behind the state of the art in digital typesetting. This is also a very classic "well I could do it better" engineer trap so please don't assume that without some research. It's an ancient d…

Do you have recommendations? (La)TeX, maybe, or *roff?

I don't have any professional typesetting experience, just some adjacency from having done some work for a type foundry at one point, that gave me some insight into how much actually goes into it.

Most professionals use expensive professional software for it. Latex or pollen or other pure markup solutions only work for smallish documents, or digital ones. Once you're going to print, esp in different formats, you need to care about page imposition, aligning with folios & signatures, widows & orphans etc. Just generally the physical reality of paper leaking into your abstraction of "the book" in ways markup alone can't accommodate.

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

#115

Post by hoofhearted »

I have used a number of different solutions over the years for simple documentation. Started with Wordpress, ended up on Docusaurus.

Docusaurus is an amazing tool for startups, but it started to show its weaknesses as we tried to scale it.

Our project requirements needed something more, so I ended up forking Docusaurus and started working on my own free open-source solution.

Check it out, I’d love to hear what everyone thinks! :)

https://github.com/elegantframework/elegant-cli

https://www.elegantframework.com/docs/installation

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

#116

Post by hoofhearted »

zoogeny wrote: post #104
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!

In all seriousness, HTML started out as a markup language for documents. That is why tags like for paragraphs and for boldness etc. are so prominent. If you aren't trying to build a SPA or something like that and you just want to mark up some text for formatted output ... HTML is kinda made for that task. That being said, I tend to stick with Markdown since I find angle bracket tags to be noisy and distracting when I…

Yes! I agree with this!

It’s just plain old dumb boring static text that is being moved around the web.

The internet was essentially created so that CERN could share plain old text documents with others remotely.

Why do I need a big bloated overly complicated PHP webserver that talks to an overly complicated database, when it’s just plain old static text after all?

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

#117

Post by slorber »

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…

Docusaurus maintainer here, happy to read your feedback ;)

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

#118

Post by geoffreymcgill »

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…

How about Retype? https://retype.com

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

#120

Post by glebd »

ShadowBanThis01 wrote: post #43

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?

Marked 2 https://marked2app.com/ is a dedicated viewer for Markdown and other text formats, but it's Mac only.
Post reply on HN