Blog Management Cheat Sheet

Cheat sheet for managing this blog. It runs on Quarto (website project) and is hosted on GitHub Pages with GitHub Actions.

Live sites: - https://geilehirnbude.github.io/notes-of-a-nerd/ (GitHub Pages URL) - https://blog.geile-hirnbude.de/ (custom domain — requires DNS to be configured, see §6)

1. How posts work

There is no build/conversion pipeline. Quarto renders Markdown (.qmd) and Jupyter notebooks (.ipynb) directly. You simply drop files into the posts/ folder:

You write/edit here	Rendered as
`posts/*.qmd`	A normal HTML post
`posts/*.ipynb`	An HTML post with the notebook rendered natively (executed if a kernel is available)

No filename convention is enforced (a YYYY-MM-DD- prefix is a nice habit for ordering). New files in posts/ appear on the homepage automatically via the listing on index.qmd.

Unlike fastpages, there is no _notebooks/ → _posts/ step, no “DO NOT EDIT / autogenerated” files, and no separate Word pipeline.

2. Writing a Markdown post (`.qmd`)

Create posts/my-post.qmd with YAML frontmatter at the top:

---
title: "My Great Post"        # quote it if it contains : ~ *
author: Lutz
date: 2026-08-06
categories: [tech]
description: "A short subtitle."
---

Common frontmatter keys:

Key	Meaning
`title`	Post title. Quote it if it contains `:`, `~`, `*`.
`author`	Author name
`date`	Publish date
`categories: [a, b]`	Tags/categories (listed on the homepage and filtered)
`description`	Blurb
`image: file.png`	Preview/social image
`draft: true`	Hide drafts during local preview (not published)

Useful Quarto Markdown

Code with syntax highlighting: triple-backtick fenced blocks (Python, R, bash, JS, …)
Math: inline $x^2$ , display $$ \int … $$ (built-in KaTeX/MathJax)

Callouts (much simpler than fastpages’ includes):

::: {.callout-note}
A note/tip/warning/important callout.
:::

Images: ![](myimage.png) — place images in the repo (e.g. an images/ folder or next to the post)
Citations: {% cite buch2026example %} and the bibliography from references.bib
```
{% cite buch2026example %}
{% bibliography --cited %}
```

3. Writing a notebook post (`.ipynb`)

Drop a Jupyter notebook into posts/ (e.g. posts/my-analysis.ipynb). Quarto renders it in place — code cells execute if a Python/Jupyter kernel is installed; outputs and figures are embedded.

Working with notebooks: - Execute/check locally: quarto preview (renders notebooks with a kernel) - Use standard Jupyter features; no special cell flags or frontmatter required. - Preview images/matplotlib output appear automatically.

4. Preview locally

quarto preview            # live preview, auto-reloads in the browser
quarto render             # build the site into _site/ (optional)

Requires Quarto installed: https://quarto.org/docs/get-started/

quarto preview rebuilds on save and refreshes the browser.
Output goes to _site/ (git-ignored).
Notebooks execute if Jupyter/a kernel is present.

5. Publishing / deploying

Publishing is just a git push to main. No build on your machine needed.

git add -A
git commit -m "Add new post"
git push origin main

On every push to main, the GitHub Action (.github/workflows/publish.yml): 1. Checks out the repo 2. Sets up Quarto 3. Renders the site and publishes it to the gh-pages branch → the site updates live (usually under a minute) 4. Watch progress in the repo’s Actions tab

No deploy key or special secrets are required (unlike fastpages’ SSH_DEPLOY_KEY).

6. Domain & HTTPS

Default URL: https://geilehirnbude.github.io/notes-of-a-nerd/ — always works.
Custom domain: blog.geile-hirnbude.de is set in Settings → Pages → Custom domain.
- ⚠️ For it to work, DNS must point the subdomain to GitHub: CNAME blog.geile-hirnbude.de → geilehirnbude.github.io (set this at your domain provider, e.g. DomainFactory — CNAME target must be the bare hostname geilehirnbude.github.io, no https:// and no /notes-of-a-nerd/ path).
- Until DNS resolves, the github.io URL is the working fallback.
HTTPS: after DNS is verified, tick Enforce HTTPS in Pages settings.

7. Editing the site itself

What	Where
Site title, description, navbar, theme	`_quarto.yml` (`website:` block)
Homepage & post listing	`index.qmd` (the `listing` block pulls in `posts/`)
About page	`about.qmd`
Site URL used in metadata	`_quarto.yml` → `website.site-url` (should match the live URL)
Bibliography / citations	`references.bib`

8. Optional features (config)

Math: built-in — no flag needed. Delimiters $...$ , $$...$$.
Search: automatic on the site (Quarto adds a search box to the navbar).
RSS / sitemap: auto-generated (sitemap.xml, feed in site_libs).
Comments: not configured by default. Add e.g. utterances or giscus in the website config or a template as needed.
Theme (format.html.theme): switch e.g. cosmo to another Bootswatch theme. See https://quarto.org/docs/output-formats/html-themes.html

9. Gotchas / troubleshooting

Quote titles containing :, ~, * to avoid YAML parse errors.
Drafts: use draft: true in frontmatter — they render only during quarto preview, not in the published site.
Broken custom domain: if blog.geile-hirnbude.de doesn’t load, it’s a DNS problem (see §6), not the build. The github.io URL should still work.
Notebooks not executing: needs a Jupyter/Python kernel available where it renders (locally). GitHub Actions CI can still render notebooks that were saved with output, or you can configure a Python setup step in the workflow if needed.
_site/ is git-ignored — never commit build output.