4 ms·

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.

Simpliplant 2y ago
I've been using Astro lately and loving it. It feels dead simple, has amazing defaults, and is easily extendable.
jyap 2y ago
A few that come to mind: Jekyll - written in Ruby Hugo - written in Go Zola - written in Rust
- dsr_ 2y ago
  Pelican - written in Python
nemosaltat 2y ago
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/ https://quarto.org/
- j_bum 2y ago
  +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.
  - nemosaltat 2y ago
    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.
    - j_bum 2y ago
      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.
    - j_bum 2y ago
      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 >}} 
- reagle 2y ago
  I’ve been waiting for them to release a standalone markdown editor, but it’s been a couple years already now.
Arnavion 2y ago
It's `pandoc --from markdown-smart --to html5` for me.
greggsy 2y ago
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://docusaurus.io/ https://vitepress.dev/ https://vitepress.dev/
ognarb 2y ago
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.
jimmar 2y ago
I’m happy with mkdocs.
wingmanjd 2y ago
It's not static, but I've enjoyed GravCMS.
thangalin 2y ago
> 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/ https://keenwrite.com/ [2]: https://dave.autonoma.ca/blog/ https://dave.autonoma.ca/blog/ [3]: https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/cmd.md https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/cmd... [4]: https://www.youtube.com/watch?v=CFCqe3A5dFg https://www.youtube.com/watch?v=CFCqe3A5dFg
jessyco 2y ago
I've enjoyed building with SveltKit reading markdown files and processing them with it, into a static hosted site.
klodolph 2y ago
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.
- dsr_ 2y ago
  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.
  - klodolph 2y ago
    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.)
- TechDebtDevin 2y ago
  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).
asicsp 2y ago
I use Zola (https://github.com/getzola/zola https://github.com/getzola/zola) - pretty fast and I was able to customize a few things as well.
- lolinder 2y ago
  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.
shepherdjerred 2y ago
https://docs.astro.build/en/tutorial/0-introduction/ https://docs.astro.build/en/tutorial/0-introduction/
arunc 2y ago
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/ https://antora.org/
lopkeny12ko 2y ago
[flagged]
- qznc 2y ago
  Isn't it a reasonable reaction, whenever you see a new (to you) product, to ask how it compares to others?
- cyberax 2y ago
  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.
bhasi 2y ago
I've been using Pelican [1] to generate my blog [2]. Here's how I set everything up: [3]. [1] https://getpelican.com/ https://getpelican.com/ [2] https://gurudas.dev/ https://gurudas.dev/ [3] https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-dev/ https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-d...
childintime 2y ago
There's nothing like Zine https://zine-ssg.io/ https://zine-ssg.io/. Alpha for now.
baxtr 2y ago
I use Jekyll. It’s pretty solid.
cryptos 2y ago
I'm satisfied with Hugo: https://gohugo.io/ https://gohugo.io/ It is very fast and has a lot of features. The syntax highlighting for code looks also very good.
brabel 2y ago
There are 355 generators on this page, many of which support markdown: https://jamstack.org/generators/ https://jamstack.org/generators/
- prmoustache 2y ago
  Pandoc, an html template for the headers/footers and optional js, a css and a small shell script is usually enough.
  - brabel 2y ago
    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.
ivanjermakov 2y ago
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.
sourcepluck 2y ago
"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/

Simpliplant 2y ago

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

jyap 2y ago

A few that come to mind: Jekyll - written in Ruby Hugo - written in Go Zola - written in Rust

dsr_ 2y ago
Pelican - written in Python

nemosaltat 2y ago

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/ https://quarto.org/

j_bum 2y ago
+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.
- nemosaltat 2y ago
  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.
  - j_bum 2y ago
    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.
  - j_bum 2y ago
    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 >}}
reagle 2y ago
I’ve been waiting for them to release a standalone markdown editor, but it’s been a couple years already now.

Arnavion 2y ago

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

greggsy 2y ago

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://docusaurus.io/ https://vitepress.dev/ https://vitepress.dev/

ognarb 2y ago

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.

jimmar 2y ago

I’m happy with mkdocs.

wingmanjd 2y ago

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

thangalin 2y ago

> 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/ https://keenwrite.com/ [2]: https://dave.autonoma.ca/blog/ https://dave.autonoma.ca/blog/ [3]: https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/cmd.md https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/cmd... [4]: https://www.youtube.com/watch?v=CFCqe3A5dFg https://www.youtube.com/watch?v=CFCqe3A5dFg

jessyco 2y ago

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

klodolph 2y ago

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.

dsr_ 2y ago
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.
- klodolph 2y ago
  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.)
TechDebtDevin 2y ago
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).

asicsp 2y ago

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

lolinder 2y ago
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.

shepherdjerred 2y ago

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

arunc 2y ago

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/ https://antora.org/

lopkeny12ko 2y ago

[flagged]

qznc 2y ago
Isn't it a reasonable reaction, whenever you see a new (to you) product, to ask how it compares to others?
cyberax 2y ago
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.

bhasi 2y ago

I've been using Pelican [1] to generate my blog [2]. Here's how I set everything up: [3]. [1] https://getpelican.com/ https://getpelican.com/ [2] https://gurudas.dev/ https://gurudas.dev/ [3] https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-dev/ https://gurudas.dev/blog/2023/06/07/how-i-generate-gurudas-d...

childintime 2y ago

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

baxtr 2y ago

I use Jekyll. It’s pretty solid.

cryptos 2y ago

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

brabel 2y ago

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

prmoustache 2y ago
Pandoc, an html template for the headers/footers and optional js, a css and a small shell script is usually enough.
- brabel 2y ago
  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.

ivanjermakov 2y ago

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.

sourcepluck 2y ago

"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/