MdBook – a command line tool to create books with Markdown | Hacker News Reader

MdBook – a command line tool to create books with Markdown

rust-lang.github.io

I am happily experimenting with Typst right now (https://typst.app/ ), which compiles much faster than LaTeX and with a syntax very similar to md, together with nice support for math, figures and advanced settings.

Typst is amazing. You try it once and never want to go back to LaTeX again.

It's been talked about here a bunch of times: https://hn.algolia.com/?q=Typst

Does anyone use Typst for multi-page documentation website? This is the most common use-case of mdbook.

Given that Typst doesn't (yet) support html output, this seems impossible. I'd absolutely love to see it though.

Typst, with MathJax for math would be ideal! But I don't want to have to learn yet another syntax for math when LaTeX's math mode is burned into my brain.

This is the main difficulty for me in learning Typst. I think LaTeX is unnecessarily verbose for simple documents. But I know its "equation part", the part within $$, well, and I don't want to have to relearn it.

Typst is great, but really doesn't really serve the primary use case of mdbook which is building documentation websites or digital knowledge gardens that are accessible as a website.

If you are typesetting a research paper or writing a technical book for print publication typst is a great solution, but for a lot folks not having web support is an absolute dealbreaker.

Apparently HTML output support is coming for typst. I'm very keen, since to be honest markdown just isn't powerful enough to support a lot of the typesetting I want to do. For example, using markdown you can't put text in boxes, reuse styles, link references to diagrams or sections, number headings, do math, and so on.

All of this stuff is crazy useful in typesetting. I love markdown, but its missing too many features.

It has been coming for a while. But I am looking forward to it. It is the only thing preventing me from using it.

Biggest downside of this tool is inability to render PDF or ePub[1]. This is why we recently switched to Quarto[2]. Typst is also a good alternative, already mentioned in other comments.

[1] https://github.com/rust-lang/mdBook/issues/815

[2] https://quarto.org/

Pandoc[1] helps to convert markdown to pdf and epub

[1] https://pandoc.org/epub.html

I know, Quarto is built on top of Pandoc.

If you want to create books, Asciidoctor (for PDF/ebook) + Antora (to publish them on the web), are the way to go. Not related, just a happy user who used Asciidoc for the last 20 years to maintain product docs.

Why? because Asciidoc/tor gives you a lot more:

- a syntax with callouts, tables, indexes, comments, notes and everything you may need in a book

- macro expansion

- a ton of complex diagrams via PlantUML (veeery useful!) that you can keep inline

- a ton of output formats, including "real" paper books via Docbook.

While we're on the topic of MD, what's the best system for Markdown-based static blogs these days? With good code highlighting, images, colors, etc.

I've been using Astro lately and loving it. It feels dead simple, has amazing defaults, and is easily extendable.

A few that come to mind:

Jekyll - written in Ruby

Hugo - written in Go

Zola - written in Rust

Pelican - written in Python

I’ve been running quarto [0] for a few months now and I’m happy with it. Posts are saved as .qmd, with a little bit of special front matter for formatting and tagging. `quarto render` converts the .qmd(s) according to a simple config file. [0] https://quarto.org/

+1 for quarto. I love it for my personal website, and I use it on a daily basis to create technical reports for my day job.

Do you have any details on your workflow for reports? I “think” in .mds and the. use a VScode extension that creates to PDF on .md save with a custom/header footer template- works 95% of the time but it’s more brittle than I’d like.

So I render all of my reports to PDFs, and I work in RStudio (love/hate relationship).

As much as I love html outputs, it’s far easier to just email a pdf to my tech unsavvy stakeholders.

I’ll share my file header and config chunks with you tomorrow when I’m at the office! I’ll ping you with a separate reply.

As promised, here is my config setup for all of my quarto scripts. In RStudio, you can simply click the "Render" button on source pane of the script to render a pdf. You can also call `rmarkdown::render("file_path.qmd", output_format = "pdf_document")` to render a PDF.

FWIW, when you click "Render", this is the output command that RStudio shows: `quarto preview FILE.qmd --to pdf --no-watch-inputs --no-browse`

Of course, you will have to remember to properly format tables, omit `&` where possible in tables, figure titles, etc. There are so many nuances, but once you've got them figured out, report generation is very smooth.

    ---
    title: Title
    author: Author Name
    date: today
    date-format: long
    pdf-engine: xelatex
    format:
      pdf:
        number-sections: true
        toc: true
        toc-depth: 3
        mainfont: Roboto  # available fonts are dependent on your machine/environment
        sansfont: Roboto
        include-in-header: 
          text: |
            \usepackage{fancyhdr}
            \usepackage{lastpage}
            \usepackage{float}
            \pagestyle{fancy}
            \fancyhead[L]{\empty}
            \fancyfoot[R]{[Company] Confidential}
            \fancyfoot[C]{\thepage\ of \pageref*{LastPage}}
    ---

    ```{r setup, echo=FALSE, include=FALSE}
    knitr::opts_chunk$set(fig.align = "center",
                          warning = FALSE,
                          echo = FALSE,
                          message = FALSE,
                          dev = "cairo_pdf")
    ```
    
    {{< include 001_QC.qmd >}}
    {{< include 002_ANALYSIS_FILE.qmd >}}
    <!-- And so on. -->

I’ve been waiting for them to release a standalone markdown editor, but it’s been a couple years already now.

It's `pandoc --from markdown-smart --to html5` for me.

VitePress and Docusaurus seem decent. I think VitePress might be more suited to blogging, but I admit I haven’t actually used or tested either.

https://docusaurus.io/

https://vitepress.dev/

I love hugo, it's a bit complex to get started with but extremely powerful. And the backward compatibility is very good, I started using that 4 years ago and aside of a handful of small issues which could be resolved in 5 min, my websites could be upgraded without any issue. This wasn't my experience with Jekyll.

I’m happy with mkdocs.

It's not static, but I've enjoyed GravCMS.

> best system for Markdown-based static blogs

I use my Markdown editor[1] to produce my blog[2].

      keenwrite.bin -q -i "${FILE_MD}" -o "${FILE_HTML}" \
        --curl-quotes=true

Offers external variable sources, too; see [3] and [4].

[1]: https://keenwrite.com/

[2]: https://dave.autonoma.ca/blog/

[3]: https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/cmd...

[4]: https://www.youtube.com/watch?v=CFCqe3A5dFg

I've enjoyed building with SveltKit reading markdown files and processing them with it, into a static hosted site.

Opinions—Hugo or Jekyll for blogs. Yes, that Jekyll! Hugo gives you more rope to shoot yourself in the foot with.

MkDocs or Docusaurus for documentation. MdBook is not in the running, IMO, unless it’s radically improved since the last time I checked.

And here’s my hot take—most generators have a lot of the same design flaws. Routing is generally a mistake—you should instead design a system where every page has a URL that directly corresponds to the source file path, if feasible. Shortcodes are a mistake—you should use custom HTML tags. SSGs should have e.g. S3+Cloudfront as a core part of their design rather than just thinking of S3 as a place you put files when you’re done.

If you use S3+Cloudfront as a core part of your design then you limit your audience to people who want dependencies on S3+Cloudfront.

That’s way off from what I meant, maybe I can clarify what I’m saying here.

You should consider the people who deploy to systems like S3+Cloudfront when designing your static site generator. Too many systems are just designed to be served from the filesystem and there are rough edges when you deploy to something like S3.

And “design for S3+Cloudfront” does not mean the same thing as “design it so that people without S3+Cloudfront are screwed”. That’s some kind of extrapolation.

The main relevant difference between e.g. S3 and a filesystem is that you can (and probably should) deploy pages to paths like /blog/hello/ rather than /blog/hello/index.html. There are other differences—it gets somewhat pervasive, unfortunately. There are hacks and workarounds but it would be nice if the SSGs were designed with cloud storage in mind as one of the core features, rather than an afterthought.

(It may seem funny that I keep saying “e.g.” but that’s because I’m not talking about S3 specifically, but speaking about a broader class of storage systems.)

I think OP is just referring to any SSG + CDN + S3, they probably just use AWS so its how they refer to it. I don't disagree.

On another note, I really like the way Cloudfront describes their "edge" offerings without having very annoying and obtuse usages of the word "edge": "Reduce latency by delivering data through 600+ globally dispersed Points of Presence (PoPs) with automated network mapping and intelligent routing."

This might be the first time I've seen anything on an AWS explained concisely and precisely /s (sorta).

Regarding MkDocs there's the great Material for MkDocs [0] for documentation.

[0] https://squidfunk.github.io/mkdocs-material/

Definitely. I think people using MkDocs should use Material as their first choice.

I use Zola (https://github.com/getzola/zola) - pretty fast and I was able to customize a few things as well.

One great thing about Zola for static sites is that it's just a binary. Hugo shares that trait, but a lot of the others are built in Python or JavaScript and therefore come with gnarly dependency trees and package management problems that have given me headaches when trying to update a site after a few years of inactivity.

With Zola you just download the same version of the binary you used last time (or even commit said binary to the repo alongside the files) and you're on your way.

It fits in well with the general static site ethos of minimalism and constancy.

https://docs.astro.build/en/tutorial/0-introduction/

I know you asked for MD based system, but if you are willing to look beyond MD, I'd encourage to look into Antora[0] that's based on AsciiDoc. It's a full fledged documentation system that can span from single article to multiple books or product or technical documentation.

[0] https://antora.org/

[flagged]

Isn't it a reasonable reaction, whenever you see a new (to you) product, to ask how it compares to others?

It's a tool for _books_, not blogs. Blogs have a somewhat different set of requirements.

I actually got a lot of good references from this thread.

I've been using Pelican [1] to generate my blog [2]. Here's how I set everything up: [3].

[1] https://getpelican.com/

[2] https://gurudas.dev/

[3] https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-d...

There's nothing like Zine https://zine-ssg.io/. Alpha for now.

I use Jekyll. It’s pretty solid.

I'm satisfied with Hugo: https://gohugo.io/ It is very fast and has a lot of features. The syntax highlighting for code looks also very good.

There are 355 generators on this page, many of which support markdown: https://jamstack.org/generators/

Pandoc, an html template for the headers/footers and optional js, a css and a small shell script is usually enough.

Can you generate (and include in a page) a list of files located in a certain directory using Pandoc? A quick look at the docs did not turn up anything, and this is something that's essential for me to create a static website.

If you want all the manual control like me, I suggest a build script that runs pandoc on .md files and injects HTML fragments into static templates.

"The best" is, of course, Haunt, written in Guile. The following list has examples, and guides and so on:

  https://awesome.haunt.page/

A few hand-picked examples:

  https://jakob.space/blog/decompilation-by-hand.html
  https://guix.gnu.org/en/download/latest/
  https://www.gnu.org/software/guile/learn/

GitHub Gist: "Document Conversion":

https://gist.github.com/datacustodian/4483fff487a0ef70c7b760...

https://en.wikipedia.org/wiki/List_of_document_markup_langua...

https://pandoc.org/

https://news.ycombinator.com/item?id=39164002

https://asciidoc.org/

Pandoc allows Markdown with fallback LaTeX which works incredibly well, imho. I suppose that is if you like both Markdown and LaTeX (along with the rest of its ecosystem).

If you have the mdbook-epub plugin, it's nice to be able to turn the myriad documentation "books" into actual ebooks that I can read on my kindle.

Moved from MD to LaTeX for documentation. Content maybe shared between two or more documents. Was copying and pasting to fix multiple locations for simple spelling errors. Now there is a single LaTex file to edit for all complete documents.

Issue is that the file system layout is more like this:

/Product A/images/

/Product A/revision.tex

/Product A/instalwin7.tex

/Product A/instalwin10.tex

/Product A/layout.tex

/Product B/layout.tex

/Commmon/images/

/Common/companyinfo.tex

/Common/header.tex

/Win7/images

/Win7/access-cmd.tex

/Win10/images

/Win10/access-cmd.tex

Where Product A and Product B layout.tex links all LaTex files needed to build a complete document.

I used it in a project once. It's a really nice and easy solution, but quite hard to extend, if the built in features are not enough.

I use `mdbook` to provide free online versions of my ebooks (topics include regular expressions, Linux CLI tools and Vim): https://github.com/learnbyexample/scripting_course#ebooks

I chose `mdbook` over `pandoc` mainly because of themes and search provided by default.

Depending on the content, I would recommend AsciiDoc (and not Markdown) to write a book. Markdown might be a good fit for text-only books like fiction, but AsciiDoc has much more useful formattings for structrured documents like technical or scientific books.

https://github.com/daviddrysdale/mdbook-asciidoc

That is a nice way to migrate to AsciiDoc. After the migration happened you can add more advanced syntax provided by AsciiDoc.

mdBook is my favorite tool for creating on-line docs. I wouldn't use it to create a printed book or a PDF, etc., but quick static documentation in HTML it works quite well. It's simple and robust and just works; and most of the limitations are due to Markdown rather than to mdBook.

If I could wave a wand and extend it in any way I chose, I'd want the ability to implement macros (or the equivalent) a la TeX, so as to automate doing fancier formatting in HTML.

Does anyone know a tool that would generate links automatically for types (etc) to Docs.rs. We have a library (Burn) and accompanying book where were references types in many places.

Looks nice. I've used MkDocs in the past for https://baseball-stats.net.

Writing a book using markdown looks very good. I’ll give it a try later if I need it.

What is a "book"? This seems to be a website.

Has anyone here actually written technical books in LaTex and Markdown that can knowledgeably compare them? How do they compare? I’m biased from university towards LaTex but the MD syntax does seem way simpler.

typscript is good

Reply on news.ycombinator.com