Hello World | Setting up my blog

2024-04-23

When setting up my blog, I had a few things in mind: - the content should just be a .md file - the ability to have code blocks, of course (code highlighting via highlight.js) - the ability to have in-line interactive content via JavaScript (and Vue.js, SVG.js) - the ability to type formulae (rendered via KaTeX) - the first line in the markdown file should be able to list all relevant metadata #blog #web #development | seo-image.jpg | features.css features.js - the folder name should be reflected in the URL, ie. 2024-04-23-setting-up-my-blog/ - // multiple language support [not supported yet]

The resulting folder structure is the following

2024-04-23-setting-up-my-blog/
   export/
      scaling-image-w600.webp
      scaling-image-w1200.webp
      scaling-image-w1800.webp
      scaling-image.jpg
   features.js
   features.css
   index.md
   seo-image.jpg

2024-05-07-my-next-blog-post/
   index.md
   ...

Languages

default: English index.md

index-en.md index-de.md

Header Line

KaTeX

As soon as a $$ is detected, the KaTeX library is loaded automatically. Typing important formulae is as easy as wrapping E = m \cdot c^2 by double-dollar-signs:

$$ E = m \cdot c^2 $$

Enhanced Markdown Media Features

Image and Video

Code

Custom JavaScript and CSS for a blog post

console.log('Hello Blog!')

Custom Enhancements — Reference

A quick summary of everything the blog engine adds on top of plain markdown.

The header line

The first line of every index.md is metadata, not content (the article body starts on line 3). All parts are optional:

#tag1 #tag2 | seo-image.jpg | features.css features.js | edited-2024-04-23

• #tag — one or more tags. The first tag is the canonical topic and forms the URL (/thoughts/<topic>/<slug>); every tag also groups the article under /thoughts/<tag>.
• seo-image.jpg / .png — social-share image, also used as the list thumbnail.
• *.css / *.js — per-article stylesheets and scripts, loaded from the article folder.
• library-katex / library-vue / library-svg — force-load that library (see below).
• edited-YYYY-MM-DD — last-edited date.

Folder name → visibility & URL

The folder name alone decides where an article shows up:

• YYYY-MM-DD-slug — public: listed on the homepage and in /thoughts. The date and slug come straight from the folder name.
• slug (no date prefix) — draft: reachable only by its direct URL, never listed.
• _slug — fixed: reachable only via a manual link (e.g. from the homepage), never listed.

Auto-loaded libraries

Libraries load only when a page needs them:

• highlight.js — loaded automatically when the article contains a backtick `.
• KaTeX — loaded automatically when the article contains $$ (or via library-katex).
• Vue.js — loaded via library-vue (dev/prod build chosen automatically).
• SVG.js (+ draggable) — loaded via library-svg.

Enhanced media

Standard image markdown ![alt](file "title") is rewritten into responsive HTML:

• Images (.jpg / .png) → a <picture> with a webp srcset at 600/1200/1800px (served from the article’s export/ folder) and intrinsic width/height to avoid layout shift. .webp / .gif become a plain sized <img>.
• Video (.mov / .mp4) → a <video controls> tag. Extra attributes can be passed before a | in the title: ![alt](clip.mp4 "autoplay loop muted | Caption text").
• The title becomes a <figcaption>; everything is wrapped in a <figure>.

Markdown extensions

Rendering uses Python-Markdown with extra (tables, fenced code, attribute lists, …), sane_lists, smarty (curly quotes and en/em dashes), and footnotes2 (numbered [^1] footnotes with superscript markers and back-links).