• Inline formatting
  • External links
  • Internal links
  • Anchor links
• Block formatting
  • Headings
  • Lists
  • Quotes
  • Monospace
  • Code blocks
  • Callout blocks
  • Horizontal rules
  • Images
  • Equations
  • Tables
• Hints
  • Widening

Update 2022-11-28 — I author my blog posts’ Markdown directly now, instead of publishing from Org-mode.

I’ve kept the original version of this page, with the What you type examples using Org syntax, even though that’s outdated for my current publishing pipeline.

The feature-set of supported formatting is still the same, I just don’t use Org syntax for things anymore.

This post illustrates the different features and formatting available for this blog. It’s partly a quick reference for myself, and partly a demonstration of what’s possible with an Org-mode based publishing solution.

The most basic formatting element is the paragraph, which is what you’re reading. In the published, styled HTML, paragraphs are separated by exactly one empty line, giving the impression of being written on lined paper.

The same vertical rhythm is maintained throughout all the formatting elements (except images and equations.) Click the following text to add lines to the background of the page to illustrate the effect:

Inline formatting

External links

Links are written in the normal Org-mode format: [[target][name]]. For example:

Since this link starts with https:, it’s considered an external link.

Internal links

In addition to external links, it’s possible to make internal links, which point to other pages in your site. Links to other Org files (such as those Org-roam creates) are handled automatically, assuming the other file was also exported.

Anchor links

Finally, you can create anchor links, which point to other parts of the same document. There are four supported types of anchors:

Block formatting

Headings

Headings are used to break a post into sections. The following heading levels are supported:

Lists

Three types of lists are supported: ordered, unordered, and description.

1. Apples
2. Bananas
3. Oranges

• An unordered list
• Left to its own devices
• Tends to fly northward

Proposition 1 : The following proposition is false.

Proposition 2 : The previous proposition is true.

Lists can be nested in a mix-and-match fashion.

• Unordered One
  1. Ordered One
  2. Ordered Two
     • Description One: What a lovely nest!
     • Description Two: Good place for a rest!
  3. Ordered Three
• Unordered Two
• Unordered Three

Quotes

This is a quote block, used for including quotations offset from the regular text.

Monospace

This is a code block,
which preserves formatting,
but has no highlighting.

Code blocks

// foo.ts
export const foo: (x: number, y: number) => {
  return x * y;
}

// index.ts
import { foo } from './foo';
foo(1, 5);

Callout blocks

Horizontal rules

Horizontal lines are written with five dashes: -----.

They’re spaced to preserve the vertical rhythm of the text.

Images

Images are supported using Org attachments:

A “direct link” to an image (e.g. View full-size image) can be done with:

[[attachment:wip1.jpg][View full-size image]]

Equations

Equations are rendered using $\KaTeX$. Block expressions ($$ ... $$) are supported:

Tables

Tables are supported:

Diagrams

Diagrams can be rendered with Mermaid:

Or with D2:

Hints

When certain formatting isn’t available in Org-mode, HTML classes can be used to adjust the way elements are rendered. This is an ad-hoc interface between the Org document and the theme’s CSS, so I like to say I’m hinting the theme about how to display the element.

Hinting is performed by wrapping the element with a div:

<div class"my-hint-class">

Thing I want to hint goes here

</div>

Generally, writing HTML directly into your Org-mode files like this is a bad practice, so hints should be kept to an absolute minimum.

Widening

The widen hint indicates that block elements should expand into the margins if the user’s screen has the real-estate for it. This is especially useful for code:

export const myUnusuallyLongVariableName: "longlonglonglonglong";