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).
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/
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.
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 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.
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.
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).
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.
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.
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.
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 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, 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.
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.
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.
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.
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.
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.
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.
70 comments
[ 3.3 ms ] story [ 136 ms ] threadGitHub 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/
Jekyll - written in Ruby
Hugo - written in Go
Zola - written in Rust
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.
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.
https://docusaurus.io/
https://vitepress.dev/
I use my Markdown editor[1] to produce my blog[2].
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
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.
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.)
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).
[0] https://squidfunk.github.io/mkdocs-material/
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.
[0] https://antora.org/
I actually got a lot of good references from this thread.
[1] https://getpelican.com/
[2] https://gurudas.dev/
[3] https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-d...
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.
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.
All of this stuff is crazy useful in typesetting. I love markdown, but its missing too many features.
I chose `mdbook` over `pandoc` mainly because of themes and search provided by default.
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.
[1] https://github.com/rust-lang/mdBook/issues/815
[2] https://quarto.org/
[1] https://pandoc.org/epub.html
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.