Writing markdown

Every .md file under the content/ directory corresponds to one page.

Right now, there’s only a single page:



~/bearcove/home-from-scratch
❯ ls content/
_index.md  templates

And it’s pretty simple:

---
title: "A new home site"
date: "1969-07-20T20:17:00Z"
---

# It's empty in here

_So many_ possibilities though!

The frontmatter

Every markdown page must start with a frontmatter block, delimited by ---, in YAML format.

You cannot use +++, it’s used for other things
You cannot use TOML, had to pick one, sorry.

The schema is:

pub struct FrontmatterIn {
    /// Title of the page
    pub title: String,

    /// Jinja2 template to use for rendering — defaults to `page.html`
    pub template: Option<String>,

    /// Publication date in RFC3339 format, e.g. `2023-10-01T12:00:00Z` (UTC)
    pub date: Rfc3339<OffsetDateTime>,

    /// Last update date, if any
    pub updated_at: Option<Rfc3339<OffsetDateTime>>,

    /// If true, page is only visible by admins
    pub draft: Option<bool>,

    /// Whether the page should be excluded from search indexing
    pub archive: Option<bool>,

    /// Code used to allow access to a draft
    pub draft_code: Option<String>,

    /// Alternative routes for this page (for redirects)
    pub aliases: Option<Vec<Route>>,

    /// Tags associated with the page (useful for listings)
    pub tags: Option<Vec<String>>,

    /// Additional metadata for the page
    pub extra: Option<FrontmatterExtrasIn>,
}

The only mandatory fields are title, and date. The latter must be in RFC3339 format.

extra fields are mostly used by templates on https://fasterthanli.me — they should be arbitrary “JSON values” but they’re not right now. It’s safe to ignore them.

Markdown features

For this section, each paragraph is doubled so you can see their sources.

The markdown processor of `home` is based on
[pulldown-cmark](https://lib.rs/crates/pulldown-cmark),
with most features enabled.

The markdown processor of home is based on pulldown-cmark, with most features enabled.

For example, it has "smart quotes", both double and 'single', as well as ~~strikethrough~~ formatting.

For example, it has “smart quotes”, both double and ‘single’, as well as ~~strikethrough~~ formatting.

It also supports inline math like $E = mc^2$ and block math:

$$
\frac{\partial f}{\partial x} = \lim_{h \to 0} \frac{f(x + h) - f(x)}{h}
$$

These are rendered using KaTeX.

It also supports inline math like $E = m c^{2}$ and block math:

$\frac{\partial f}{\partial x} = \lim_{h \to 0} \frac{f (x + h) - f (x)}{h}$

These are rendered using pulldown-latex, which generates MathML.

The Latin Modern Math font is shipped within home-base and included by default in the main.scss generated by home init.

Fenced code blocks

You can include code blocks with triple-backticks followed by the language.

As of home v33, the following languages are highlighted:

Assembly (asm, x86asm)
Bash (bash)
C/C++ (c, cpp)
Clojure (clojure)
Common Lisp (commonlisp)
CSS (css)
SCSS (scss)
Diff (diff)
Dockerfile
Emacs Lisp (emacslisp)
Go (go)
HTML (html)
INI (meson-wrap)
Java (java)
JavaScript (javascript, js)
Jinja (jinja)
JSON (json)
LaTeX (latex)
Markdown (markdown, md)
Meson (meson)
Nix (nix)
PowerShell (pwsh, pwsh-script)
Python (python)
Rust (rust)
Shell (shell)
TOML (toml)
TypeScript (typescript, ts)
TypeScript React (tsx)
XML (xml)
YAML (yaml, yml)
Zig (zig)

Terminal sessions

The home term command captures a terminal session and writes a term block to the pasteboard (and to disk).

Here’s a demo with fastfetch:



~
❯ fastfetch
                     ..'          amos@crepe
                 ,xNMM.           ----------
               .OMMMMo            OS: macOS Sequoia 15.3.2 arm64
               lMM"               Host: MacBook Pro (13-inch, M2, 2022)
     .;loddo:.  .olloddol;.       Kernel: Darwin 24.3.0
   cKMMMMMMMMMMNWMMMMMMMMMM0:     Uptime: 21 hours, 45 mins
 .KMMMMMMMMMMMMMMMMMMMMMMMWd.     Packages: 248 (brew), 8 (brew-cask)
 XMMMMMMMMMMMMMMMMMMMMMMMX.       Shell: fish 4.0.1
;MMMMMMMMMMMMMMMMMMMMMMMM:        Display (Color LCD): 2560x1600 @ 60 Hz (as 1280x800) in 13" [Built-in]
:MMMMMMMMMMMMMMMMMMMMMMMM:        DE: Aqua
.MMMMMMMMMMMMMMMMMMMMMMMMX.       WM: Quartz Compositor 278.2.7
 kMMMMMMMMMMMMMMMMMMMMMMMMWd.     WM Theme: Multicolor (Light)
 'XMMMMMMMMMMMMMMMMMMMMMMMMMMk    Font: .AppleSystemUIFont [System], Helvetica [User]
  'XMMMMMMMMMMMMMMMMMMMMMMMMK.    Cursor: Fill - Black, Outline - White (32px)
    kMMMMMMMMMMMMMMMMMMMMMMd      Terminal: home
     ;KMMMMMMMWXXWMMMMMMMk.       CPU: Apple M2 (8) @ 3.50 GHz
       "cooc*"    "*coo'"         GPU: Apple M2 (10) @ 1.40 GHz [Integrated]
                                  Memory: 6.45 GiB / 8.00 GiB (81%)
                                  Swap: 383.56 MiB / 2.00 GiB (19%)
                                  Disk (/): 410.83 GiB / 460.43 GiB (89%) - apfs [Read-only]
                                  Local IP (en0): 192.168.1.85/24
                                  Battery (bq20z451): 78% (6 hours, 32 mins remaining) [Discharging]
                                  Locale: en_US.UTF-8

From the recorder’s perspective, it looks like:

A screenshot of Ghostty showing the home term command, then the fast fetch command, and then getting out of there. It says that it wrote output to the macOS scriptboard and to /tmp/terminus-output

Inserting media

Images, SVG diagrams, and videos can be dragged onto a home site viewed locally:

Inserting videos works almost the same except the video is transcoded before you're able to insert it.

If you specify a title, attribution, or attribution_link, then it’s inserted as a figure shortcode, rather than a media shortcode.