Essay Metadata

Markdown essays must start with a YAML Pandoc metadata header; this is only one YAML metadata header per file. Validation of enumerations & per-page uniqueness is done in hakyll.hs during compilation.

The order of all fields is: title, author, description, thumbnail, thumbnail-text, created, modified, thumbnail-css, status, confidence, importance, css-extension.

Mandatory fields:

• title: sets the page title and the first <h1> header; written in simple inline HTML (eg. italics, smallcaps, subscripts/superscripts, but not bold or links/footnotes); <13 words.

• description: short (20–650 characters) inline-HTML summary of the page; level of detail should be in between the title and the abstract.

  Lightweight “blog” posts (path starting with /blog/) are exempted from the description requirement.

• created: “YYYY-MM-DD”; must be after “2008-01-01” and before tomorrow.

• status: enumerated list of writing completion (“finished”, “in progress”, “draft”, “notes”, “abandoned”, “obsolete”)

Optional fields:

• author: comma-separated list of authors, same format as annotations.

  If not set, the author is assumed to be “Gwern”. If it is someone else, it may be a good idea to include an explicit in-page byline, using <div class="text-center">by author</div>.

  Authors should have a homepage/profile URL defined in Config.Metadata.Author. AI authors should be listed as well as human authors; unless a piece is ~100% AI-generated (and this is clearly noted), then the lead human author should be listed first, as they are responsible for the page as a whole.

• modified: “YYYY-MM-DD”; must be after “2008-01-01” and before tomorrow.

• confidence: a single extended Kesselman estimative word

• importance 0–10

• css-extension: space-separated HTML classes which will be substituted in per page

  These are used to style an entire page and control things like the page dropcaps, dark vs light vs holiday theme, etc.

  Example of a field: css-extension: dropcaps-cheshire reader-mode would make a page use the Cheshire Art Deco dropcap while turning on reader-mode by default to reduce visual clutter.

  Examples of values: dark-mode • dropcap-not • dropcaps-cheshire • dropcaps-de-zs • dropcaps-dropcat • dropcaps-gene-wolfe • dropcaps-goudy • dropcaps-kanzlei • dropcaps-yinit • extract-not • index • reader-mode • test-april-fools-2024 • test-april-fools-2025 • test-april-fools-2026 • test-christmas • test-easter • test-halloween • toc-not

• thumbnail: absolute image path (eg. /doc/cs/shell/2024-01-17-cmatrix-matrixstylescreenscroll.png); local image must exist. The thumbnail is used in social media previews, annotation popups of a page, and may be automatically displayed in the page abstract to add flair.

  • Thumbnail reuse: it is common (esp. on poetry/fiction pages) to use the same image as both thumbnail and an in-body full-width figure. In that case, reuse the thumbnail-text as the img title= (or otherwise ensure they stay consistent).

• thumbnail-text: inline-HTML caption text for the thumbnail (displayed in link previews/popups).

  May be lengthy and include hyperlinks etc. Desirable but optional.

• thumbnail-css: CSS classes applied to the thumbnail image (eg. .invert-not for images that shouldn’t invert in dark mode, like thumbnail-css: invert-not outline)

• placeholder boolean “True”/“False”

• index: boolean

• error404: boolean

• backlink: boolean

Example YAML front-matter, based on this page:

​-​--
title: "Manual of Style"
description: "Style guide documentation of Gwern.net writing conventions for essays and code."
thumbnail: /doc/ai/nn/transformer/gpt/dall-e/4o/2026-01-07-gwern-gpt5-thevelveteenrabbit-velveteenaishoggoth-simplifiedforthumbnail.png
thumbnail-text: "The Velveteen Shoggoth: if a boy loves a shoggoth long enough and hard enough, can it turn into a <em>real</em> rabbit...?"
created: 2025-05-07
modified: 2026-01-14
status: in progress
confidence: certain
css-extension: dropcaps-kanzlei
...

Transclusion

A signature Gwern.net site feature is a rich set of client-side transclusion primitives (see transclude.js), which allow copying into the current page an almost arbitrary set of other pages or parts of pages or metadata about pages. This allows avoidance of repetition, and is tightly integrated into the popups, backlinks, and local archive features. (This is a major Gwern.net design pattern used to build up many things such as popups of annotations—which lazy-load the document, and auxiliary links.)

They are “lazy”, and done client-side in JS to allow arbitrarily large deep amounts of recursive transclusion, including loops. They are written as HTML classes on a link.

Use-cases:

• DRY of boilerplate or repeated text

• migration of parts of pages: transclude the annotation to summarize what used to be there, while automatically redirecting readers to the new location

• precise range citation of a specific part of a sentence, or paragraph, or section, by defining a span/div wrapper with an ID, and linking or transcluding that ID

• reader-friendly longform: including a large text blob in a reader-friendly way by transcluding it inside a collapsed region ([text URL]{.include .collapse})

• combining auto-generated pages with hand-written pages: the auto-generated page simply transcludes the path of a hand-written page. (Example: tag-directory indexes like /doc/foo/index will transclude a /doc/foo/abstract, if it exists, to summarize or describe the tag.)

Common uses:

• .include: copy everything at the URL in; this is scoped to the ID (eg. a section)

  • .include-strict: perform the transclusion as soon as possible, non-lazily; typically useful as a performance optimization, to ensure readers don’t have to wait, or to ensure that a link target ID exists

• .include-annotation: transclude the annotation as a block, with its metadata header, excerpts/abstract/commentary, etc.

  Especially useful in bibliography-like pages.

URLs

Site essay URLs follow the ‘slug’ pattern: one or two alphanumeric hyphen-separated keywords, avoiding plural endings to reduce ambiguity (eg. /sidenote, not /sidenotes). HTML essay pages are “cool URIs” which have no extension. Conventions:

• “Graveyard”: pages which contain ‘outtakes’, ‘failures’, ‘prototypes’, ‘rough drafts’ etc. of a final polished product; they are named with the -graveyard suffix, so /foo-graveyard for /foo (eg. /face-graveyard records failed attempts at generating the successful StyleGAN anime faces in /face).

• “Lorem”: prefix of pages testing out site functionality, split due to size & browser stress

• Topic groups: directories for organizing essays by theme (eg. fiction haskell newsletter nootropic review sicp zeo). Generally self-explanatory, but note that newsletters follow a strict /newsletter/YYYY/MM.md naming convention with an optional /newsletter/YYYY/13.md for annual newsletters.

  Or by document type: blog doc note. (Blogs are short posts intended to be easier to write than a full essay page; the document hierarchy encodes the hierarchical tag system & all hosted files, and notes are currently something of an atavism, which are deprecated in favor of more sophisticated use of blogs or tags with transcluded abstracts.)

All URLs should be fulltext links if humanly possible.

URLs should link to the most relevant anchor inside a URL. In the case of PDFs, one should link to a specific page using an anchor ID like #page=n.

URLs written in foreign languages should be identified with a language code (eg. ).

Files follow the naming pattern YYYY[-MM[-DD]]-surname[-description][-nth].ext. (This is memorable, predictable, short, and sorts well on the command line.) If there is no surname, it uses the closest available entity name; if there is nothing at all, “anonymous”. If there are collisions, they are disambiguated by tacking on a count: eg. 2026-foo-1.pdf vs 2026-foo-2.pdf. For more complicated documents, such as books or generated images, it can be worth encoding descriptions or titles; like a book is better named 2026-foo-title.pdf to make it more findable. For image files, given how hard they are to work with or refind later, it is best to specify a lot of data, like an author (and/or tool), exact date, and description (eg. 2025-01-01-gwern-gpt4o-frogmeme-description.png).

File formats should be on the file type whitelist. We are conservative in allowed file formats; images should be JPG/PNG, avoiding WebP/AVIF (see Image.hs); documents should be PDF and not DjVu; archives should be XZ-compressed tarballs, etc. Large-files >250MB are specially supported. All file formats should have a link-icon. (The link-icon test page doubles as the file type whitelist.)

Image files are compressed automatically.

Inline

• Dashes: I require correct use—hyphens for regular spelling, en-dashes for ranges, em-dashes for comments. (Em-dashes are not space-separated.)

• Dropcaps: dropcaps are chosen by topic (tests):

  • Dropcats: cat

  • Goudy: biological

  • Cheshire: literary

  • De-Zs: non-technical or general articles

  • Kanzlei: technical

  • yinit: highly technical

  • Gene Wolfe: Wolfe-fiction-related essays

  When a new essay is written and the dropcaps set picked, the list of current uses of that dropcaps set (stored in the dropcaps page) should be consulted, and the first paragraph (after the abstract) rewritten to try to use an unused dropcap letter. (Or if that turns out to be difficult because the unused letters are rare ones like ‘Z’, at least avoid the most overused letters.)

  Do not start pages with quotations or numbers if a dropcap is desired.

  Dropcaps are set on a page-level with dropcaps-$THEME (eg. css-extension: dropcaps-yinit), and on a per-block basis with dropcap-$THEME (eg. <div class="abstract-collapse dropcap-yinit">); the latter overrides the former. (Dropcaps are always available in both versions.)

• Currency/Inflation: all currency amounts should be written with American decimal notation (eg. $1,234.56).

  Dollar/₿ prices or values should be inflation-adjusted if they reflect some real transaction or amount, rather than being placeholders, especially in any historical context. This includes in quotes, as the original nominal amount is still available to the reader.

  If you buy something for ‘$1’ in 2026, it should be written [$1]($2026) to be appropriately adjusted for the future inflation by Inflation.hs; whereas if it’s describing an economics or thought experiment and is just an arbitrary unit of value, it should be left as-is. (It would be confusing if 10 years from now, an essay asked you to imagine Omega flying up to you and offering you ‘$1.21’ if it correctly predicts your response…)

  Due to the extreme volatility, ₿ amounts must be written with a specific YYYY-MM-DD date like [₿1](₿2026-01-01). For details, see Inflation.hs/Config.Inflation.hs.

• Exclamation: instead of writing ‘?​!’, I condense to an interrobang.²

• Links: the first instance of any term or citation should be hyperlinked.

  All later uses should be unlinked, or they should link to the first one’s anchor. (This is usually unnecessary, but in large essays or ones with relatively independent sections, this may be helpful.)

• Lists: the start of a list item is capitalized. List items should begin with a label: a colon-separated keyword or phrase which can be emphasized.

  Inline lists can be comma-separated, or optionally use a BULLET ‘•’ point.

• margin notes: very short summaries.

  Our ‘margin notes’ are a custom kind of sidenote, which are typeset in the left margin without a number, or left italicized inline. (They are enabled in annotation as well as essays.) They summarize a paragraph, but are not used for asides or digressions like sidenotes/footnotes. (This is why they are left of the paragraph they summarize.) If there is more than one margin note, they are also copied to an indented list at the beginning of the section to serve, Victorian-style, as a micro-table of contents.

  Conceptually, they are like a deeper level of headers; HTML headers only allow for 6 levels (h1–h6), and this is not always enough, especially if one wants to summarize each paragraph. (For example, if this were not a list item, the phrase “margin notes” would be an acceptable margin note.) So our span.marginnote class allows taking a 1–3 word phrase (longer typically looks unnatural), and setting it in the left margin or leaving it inline and italicized.

  If a section has only 1 paragraph (even if it is a long complex paragraph), a margin note should not be used, because the section header should already cover it.

• Math:

  • HTML inline math: inline equations are written using pure HTML/Unicode/CSS: many math glyphs are already available in Unicode

    • LaTeX equations are auto-converted using the script latex2unicode.py, which has a comprehensive set of rules & examples.

      If latex2unicode.py refuses to convert an expression, then it probably should not be converted. Complex block equations, particularly horizontal lines, are not currently supported (but may be possible at some point using raw HTML <table> with rowspan/colspan, eg.).

    • simple Markdown super/subscripts: use the standard Pandoc ^superscript^/~subscript~ syntax;

    • complex HTML super/subscripts: like a superscripted variable over a subscripted variable, can be done in custom CSS.

      I defined a span.subsup which does this. To use that, simply write <span class="subsup"><sub>Bottom</sub><sup>Top</sup></span>. (We write the subscript first to reduce the risk of Pandoc misinterpreting it as a footnote.)

    • multiplication: use MULTIPLICATION SIGN ‘×’ for multiplication in arithmetic; MIDDLE DOT ‘·’ for contexts where there may be an x variable (eg. not 𝒪(n × log n) but 𝒪(n · log n)).

    • division: use FRACTION SLASH for compact vulgar fractions (eg. “7/11 is a food chain” vs “7⁄11 vaccinated mice survived”)

    • Logotypes: use LaTeX/T_eX logotypes (written as <span class="logotype-latex">L<span class="logotype-latex-a">a</span>T<span class="logotype-latex-e">e</span>X</span>/<span class="logotype-tex">T<sub>e</sub>X</span>). Compounds are written the obvious way.

• Ordinals: the extension (eg. ‘th’, ‘nd’) is superscripted (not “1st” but 1<sup>st</sup> or 1^st^)

  Note that some uses of ordinals could be replaced by our ‘progress indicators’, but they are difficult to write by hand and generally better left to infrastructure.

• Smallcaps: smallcaps are written using a span.smallcaps class (similar to Pandoc’s default CSS). We prefer Markdown syntax where possible, like [Smallcaps]{.smallcaps}. (Note that smallcaps requires some lowercase letters or else it is pointless, as uppercase smallcaps = uppercase, and so one should never smallcaps an all-uppercase string.)

  They are used for emphasis as the third level, and in the site UI like styling some levels of headers.

  The first line of the first paragraph of an essay is set in smallcaps for style; if this is undesirable, it can be explicitly disabled using .smallcaps-not.

• Wikipedia links: should be written using the Interwiki.hs !W shortcut syntax: ie. not [George Washington](https://en.wikipedia.org/wiki/George_Washington) but [George Washington](!W) or <a href="!W">George Washington</a>.

  The WP article is inferred from the anchor text, and is overridden in Markdown/HTML by specifying the link title instead, like [President Washington](!W "George Washington"). Never repeat the target or use a redundant full WP URL (ie. do not write [George Washington](!W "George Washington") or [George Washington](https://en.wikipedia.org/wiki/George_Washington) but just [George Washington](!W)). The target may or may not be URL-encoded. (Only a few interwiki targets beyond English Wikipedia are supported: !Hackage, !Hawiki, !Hoogle, !Wikiquote, !Wiktionary. All other wikis or Wikipedias must be linked normally.)

  The frontend JS code automatically handles annotations for WP articles by calling the WP API.

• Poetry: inline poetry is formatted using slashes and the span.poem class. See § Poetry for details.

  Note that poetry is permitted to violate all regular style rules if necessary, as long as the violations are documented as intentional & whitelisted in a comment.

• Annotations:

  You cannot link an ID inside an annotation. If you need granular addressing of an annotation, see the annotation anchor trick.

  The annotation anchor trick: An annotation design pattern is to provide multiple single-topic annotations for the same URL, rather than one large multi-topic annotation. For example, a PDF could be annotated repeatedly, with a different page each time, like /doc/foo.pdf vs /doc/foo.pdf#page=10 vs /doc/foo.pdf#page=15 (adding a section title to disambiguate, like “Title” vs “Title § Methods” vs “Title § Conclusions”); web pages likewise can be annotated using different anchors. The annotations can of course link each other, or transclude each other (using .include-annotation-core to avoid repeating the metadata header), possibly in collapses, so one could have a ‘master’ annotation of the naked URL and then transclude in 3 sub-annotations, as it were (eg. Raphelson1980).

  Sometimes there is not a useful ID already; for documents hosted on Gwern.net, they can just be edited to include anchor IDs as necessary, but for other URLs (eg. web pages completely devoid of IDs), we can simply create a fake anchor ID for each separate topic, and annotate those. (This may create false positives when checking links, but oh well.)

Block

• Admonitions (demos): admonitions (sometimes ‘callouts’ or ‘pullquotes’) are intended for warnings or alerts where simply bolding some text won’t do. They are a div.admonition [tip/note/warning/error] wrapper around a <p> and possibly a div.admonition-title.

  Fully-written-out example (avoiding ‘native’ Pandoc div syntax as usual):

  <div class="admonition tip">
     <div class="admonition-title"><p>Tip Title</p></div>
  
     <p>Tip.</p>
  </div>

• Epigraphs: are a div.epigraph wrapper around a blockquote.

  The blockquote is italicized; the text is not normally wrapped in double-quotation marks (unless a dialogue) because that would be redundant with the fancy CSS ‘quotes’ around the epigraph as a whole. The optional final paragraph is roman, and is usually the attribution of the quote; this is denoted by an em dash. Example:

  <div class="epigraph">
  > Fourscore and 7 years ago...
  >
  > ---Abraham Lincoln (1863)
  </div>

  The attribution is usually the author, full name or surname, and then a source & year in parentheses. But this can vary for effect—sometimes it will be funnier to attribute it to a character instead (in which case I put the author in the parentheses).

• Footnotes/Sidenotes: the same thing, chosen based on responsive design. Standard Pandoc Markdown syntax for footnotes like [^id]: Content. or ^[Content.].

  The ID should be be usable as a descriptive human-readable HTML ID—a lowercase alphanumeric hyphen-separated phrase similar to the URL slugs, and should meaningfully summarize the context. (They should not be mere numbers.)

  They are not used for simple citations, as that is better handled by linking a fulltext URL + annotation. They are used for detailed citations (eg. translation), multiple citations, complex citations like excerpts, and digressions or tangents. Length-wise, they should be less than 200 words; anything longer is better refactored into something else (an annotation, a collapse, an appendix…).

  Block footnotes, where the footnote body is defined separately, are usually located immediately after the Markdown element they are used in, for easier editing. (They are not grouped at the end of the Markdown document.) If at the end of a sentence, they are placed after sentence-ending punctuation and not before.

  Footnotes are sometimes worth linking. Unfortunately, Pandoc chooses not to use the ID to define a linkable anchor, due to concerns about creating collisions. In that case, they can be linked by defining an empty span with the ID, like These IDs, like all other IDs, must be unique.

• Paragraphs: relatively long paragraphs are preferred compared to the usual Internet social media/blog writing style of 1 sentence per paragraph.

• Lists:

  • Ordered vs unordered: if a list might be referred to by number/position, then it should be ordered. If not, it should be unordered.

    However, even ‘unordered’ lists should be as ordered (or ‘seriated’) as possible. There may not be a canonical ordering, but almost all lists can be put into some order more meaningful than a randomized shuffle: similarity, descending order of importance, or even just alphabetically!

  • Columns: if a list is composed of >6 items which are ‘short’ (maybe <30 characters), then it is a good candidate for formatting as a multi-column list which will wrap as 2 columns. This is a div.columns wrapper.

• Emphasis: nesting level, especially in unordered lists where keywords or phrases will be emphasized, is indicated by a 3-cycle: strong → italics → Smallcaps → strong …

  I prefer to use Markdown bold & italic syntax.

• Abstracts: an abstract is a div.abstract which contains a blockquote summarizing a section or a page. There may be multiple abstracts on a page, especially for appendixes.

  All abstracts should be broken up into multiple paragraphs. They should try to follow the standard scientific writing of ‘background, data, methods, results, conclusion’. (paragraphizer.py attempts to do this automatically using an LLM.) They may contain additional block elements like lists or nested blockquotes or admonitions.

  Essay abstracts power the annotation of their URL, as they get scraped monthly and turned into an annotation. If this is undesirable, set .scrape-abstract-not on the abstract.

• Images: Use <figure> elements.

  • caption format: start with a bold ‘Figure’, then the 1-sentence summary is italicized, and a linebreak (a <br>)³ separates the detailed description. The detailed description has parenthetical labels A–Z, which are italicized. (And if further emphasis is necessary, then, following the bold/italic/smallcaps convention, smallcaps is used.) So a Markdown caption of a paper’s “Figure 1” might go like this:

    Since many image captions are copied from a document and are not necessarily what I would have written, it can be a good idea to include a title attribute describing the image. (Both caption and title will be displayed by image-focus.js when the reader zooms in on an image, so neither is wasted.)

    Figures are not usually named or numbered in essays, and so do not need a **Figure N** prefix.

  • layout: images can be laid out with .width-full, .float-right, and .float-left. They can also be collapsed.

    Full-width images are useful for decorative illustrations, or highly-detailed images (eg. scientific paper figures might have 10 figures packed into a single one).

    Floating is useful for smaller images; usually, in accordance with the left-to-right pattern, images will be floated-right. If there are multiple images, they may zig-zag right/left/right to avoid ‘stacking up’.

  • Dark-mode: inversion during dark-mode is controlled by InvertOrNot.com by default, but it can be overridden by specifying .invert (eg. black-on-white line art) vs .invert-not (eg. photographs, color art).

    (Time permitting, explicitly mark images with .invert/.invert-not, as this is more reliable & saves network requests/latency.)

  • Borders: Outlined by default.

    They can be manually outlined or not outlined using .outline/.outline-not (which can be important in dark-mode or for .width-full decorative images).

  • Navigation: images can be click-to-zoom and automatically viewed in a ‘carousel’ by image-focus.js; no additional metadata is necessary.

• Video: Pandoc does not have any video syntax, so it must be written in raw HTML, using the backtick syntax.

  Videos should usually avoid looping (unless clearly ‘GIF-like’), autoplaying, or loading the entire video (ie. default to preload="none"), and should provide controls; allowed video formats are MP4/WebM. They should include the width/height/aspect ratio (defined in a custom data-attribute) and a caption

  An example video of a statistical visualization, with looping enabled to help the viewer see the evolution from start to finish:

  ```{=HTML}
  <figure>
      <video controls="controls" preload="none" loop height="1080" width="1920" data-aspect-ratio="16 / 9">
          <source src="/doc/tea/gwern-tea-mineralwaters-bestarm-sequential.mp4" type="video/mp4">
      </video>
      <figcaption>Animation of mineral water taste-test showing how the posterior distributions evolve over <em>n</em> = 7 to <em>n</em> = 67, guided by Bayesian best arm sampling. MP4 testcase.</figcaption>
  </figure>
  ```

• Interview: interviews are formatted specially to vertically align the speakers and indent the responses, and group the conversation by topic.

  They are div.interview wrappers, containing unordered lists of bold speaker-name / colon / quote (not necessarily strict Q&A), where <hr> horizontal rulers separate ‘topics’. Example:

  - **A**: Question 1?
  - **B**: Answer 1.
  - **A**: Commentary.
  
  ​-​--
  
  - **A**: Question 2?
  - **B**: Answer 2.

• GTX metadata databases: annotations & metadata are stored in a custom line-delimited file format called GTX, which avoids drawbacks of YAML/JSON for writing many complicated HTML snippets.

  See GTX.hs for a detailed description of the syntax and the design rationale.

  GTXs are split by level of quality, for easier editing/revision-control: me.gtx (Gwern-written essays etc.), full.gtx (hand-curated annotations), half.gtx (mix of edited & automatically-generated), auto.gtx (fully automatically generated).

• Math: complex block equations are written in LaTeX and typeset by MathJax. They are written in the normal Pandoc $$block equation$$/$inline equation$ syntax.

  In some cases, a block equation may, like many inline math equations, be feasible using pure HTML/Unicode/CSS; if they are (ie. the latex2unicode.py script can handle them and they are not complex nested fractions, integrals, matrices etc.), they should be done that way, as the pure approach has several advantages (it can eliminate the need to load heavyweight Mathjax CSS/fonts, looks more natural, reduces risk of long-term bitrot, is more searchable etc.)

• Tables: Pandoc supports several kinds of Markdown tables. I usually use either ‘simple’ tables, or pipe tables; ‘grid tables’ having proven to be more trouble than they are worth despite an Emacs mode. (Generally, if one finds oneself rejiggering the whitespace in a simple table, it is time to move to a pipe table.)

  Ideally, all tables would be recreated in pure Markdown, but that is often too much work, or infeasible in the case of complex tables which may split columns etc. (eg. 1, 2); screenshots are permitted.

  Tables are usually given titles/captions; the Pandoc syntax is a blank line then “Table: …”. Table captions are full sentences with normal formatting. (We do not ever write <figcaption> captions in Markdown.)

  Layout: Pandoc supports simple table layout control like the relative widths of columns (# of hyphens in column header), and left/right/center alignment of each column (colon on left/right/both sides in header).

  We provide additional control: much like figure images, tables can be floated left/right, or made full-width; they can also be compacted with .table-small. Particularly in annotations, for a very small table, like a 2×2 table, it is good to use both and wrap it in a <div class="float-right table-small">. Example:

  <div class="float-right table-small">
  | 1 | 2 |
  |---|---|
  | 3 | 4 |
  | 5 | 6 |
  
  Table: A small 'inline' table writen as a demo for the Style Guide.
  </div>

  Tables are zebra-stripped by custom CSS, and sorting is done with tablesorter.js; sorting is disabled using .table-sort-not. They are generally not otherwise styled.

  Tables can be collapsed; the collapse will show the first few lines. If one wants to provide a summary or key lines, one can use .abstract-collapse-only.

• Horizontal ruler: can be considered as an “anonymous section”, when we don’t want to write a title & add another Table of Content, or we have already gone uncomfortably deep, like 7-levels deep.

Poetry

Poems on Gwern.net are not formatted using block or code block tags, but using custom CSS classes set on div/span/pre tags. (For background on the design rationale, see the detailed “Poetry HTML Typesetting” writeup.)

Mobile does not receive any special treatment: mobile poems are rendered just like desktop poems, albeit with a narrow window.

<div class="poem">
**_Dear Santa_**, pray accept this urgent plea \
And burn your police reports regarding me. \
I write to clear my name of wicked lies, \
That cast me as a fiend in festive guise!
</div>

<div class="poem">
So much / depends upon
...
</div>

So much
        depends upon

<div class="poem">
For we can always see and feel much that the people in old photos and newsreels could not:

that their clothing and automobiles were old-fashioned, \
that their landscape lacked skyscrapers and other contemporary buildings, \
that their world was black / and white / and haunting / and gone.
</div>

For we can always see & feel much that the people in old photos & newsreels could not:

that their clothing and automobiles were old-fashioned,
that their landscape lacked skyscrapers and other contemporary buildings,
that their world was black
                           and white
                                     and haunting
                                                  and gone.

<div class="poem">
> In they hacked them, || out they hurled them, \
> bears assailing, || boars defending. \
> Stones and stairways || streamed and darkened; \
> day came dimly— || the doors were held.
</div>

> <div class="poem">
> There are strange things done in the midnight sun \
> By the men who moil for gold; \
> The Arctic trails have their secret tales \
> That would make your blood run cold; \
> The Northern Lights have seen queer sights, \
> But the queerest they ever did see \
> Was that night on the marge of Lake Lebarge \
> I cremated Sam McGee.
> </div>

<div class="epigraph poem" id="example-poem-2">
> Roses are red <!-- 4: RO1-ses2 are3 RED4. [red/—] --> \
> Violets are blue <!-- 5: VI1-o2-lets3 are4 BLUE5. [blue/you] --> \
> And I love you. <!-- 4: and1 I2 LOVE3 YOU4. [blue/you] --> <!-- NOTE: foo -->
>
> ---[Anonymous](!W "Roses Are Red")
</div>

```{=HTML}
<!-- NOTE: `pre.poem-html` to force exact vertical alignment rather than enjambment: -->
<pre class="poem-html" id="complex-block-poetry-example">
Their hands remembered stillness in the air,
                                    <em>care</em>
...
</pre>
```

Bash

Gwern.net Bash scripts are Bash-only, GNU/Linux-only, well documented, and optimized for long-term maintenance rather than minimalism. Readability, explicitness, and debugging are key.

• Shell: GNU bash, not POSIX sh.

  Arrays, associative arrays, [[ … ]], ${var^^}, process substitution, and exported functions are permitted.

• Userland: GNU/Linux coreutils assumed unless otherwise documented.

  • Apple/BSD are unimportant and unsupported, especially given the outdated and poorly supported macOS userland.

• Working directory: usually ~/wiki/static/build/ or ~/wiki/. Convert the absolute Gwern.net paths using the path2File/file2Path utility functions (eg. /doc/foo.pdf → ~/wiki/doc/foo.pdf)

• Helper functions: utility functions are defined in bash.sh.

• Error handling:

  • Scripts must fail fast, using set -e; fatal preconditions (missing tools, missing directories, bad arguments) must exit (script)/return (library) immediately with a clear message and a unique exit code.

  • Explicitly ignore errors: use || true, or a clearly-scoped set +e … set -e island to selectively run tests which may fail (see the wrapping idiom) Never rely on implicit set -e exceptions or on bash.sh enabling set -e.

  • set -euo pipefail is allowed inside contained helpers where all variables and pipes are controlled (eg. find_colliding_files())

    Do not enable globally unless every variable expansion has been audited. Each exit/return should use a different integer to make it easier to grep for provenance. (The integers do not need to mean anything, but it is helpful if they are in rough order of execution.)

  • Recoverable failures are logged as warnings (using the helper function red) and execution continues.

• Flags, options, and command style:

  • Always use long flags: sort --unique, not sort -u.

    Where this might be cumbersome, like grep --fixed-strings, aliases can be added to hardwire long flags (eg. the grep DSL, gf/ge/gfv/gev/gfc/gec: g for grep, v for negation or filtering out, f/e for fixed vs regexp, and c for terminal coloring of positive hits)

  • Terminate options explicitly in any file-argument scenario to reduce risk: rm -- "$FILE".

  • Prefer explicit GNU flags over positional magic (--max-args, --recursive, --null, etc.).

• Quote everything unless word-splitting or globbing is deliberate and documented.

  Gwern.net filenames are required to be whitespace-free, but it is unsafe to assume this, and filenames with whitespace should be handled.

• Arrays over strings for lists.

• Reading lines must be robust:

  while IFS= read -r line; do
      …
  done

  Any temporary IFS modification must be tightly scoped and commented.

• Variables & naming:

  • Globals / configuration: ALL_CAPS.

  • Locals: declared with local, grouped at function top.

  • Arrays: ("${array[@]}") when expanding.

  • Associative arrays: only when keys are semantically meaningful.

• Aliases: preferred over functions if there is no handling of arguments; especially good for more ergonomic names or preventing typos (eg. alias pdfcut="pdf-cut")

• Function definitions: single-use internal functions can be declared inside a function if that would read better

• Haskell interoperability:

  Use runghc for scripts or ghci -e for one-liners.

  Note that you must import modules explicitly in one-liners: eg. ghci -e 'do { md <- LinkMetadata.readLinkMetadata; ... }'. Do not assume any module is implicitly imported.

command \
    --option-1 \
    `# rationale for option-2` \
    --option-2 \
    `# --option-3  # TODO: re-enable after fixing upstream bug`

#!/usr/bin/env bash
#
# script-name.sh—one-line description of purpose
#
# Author: Gwern Branwen
# Date: YYYY-MM-DD
# When: Time-stamp: "<YYYY-MM-DD HH:MM:SS gwern>"
# License: CC-0
#
# Usage:
#   ./script-name.sh [OPTIONS] ARG…
#
# Notes:
# - Bash-only; GNU userland assumed.
# - Fails fast; recoverable errors are explicitly ignored.
#

set -e

cd ~/wiki/static/build/

########################################
# Imports
########################################

# shellcheck source=./bash.sh
. ./static/build/bash.sh

########################################
# Configuration
########################################

VERBOSE=0
DRY_RUN=0

########################################
# Helpers
########################################

usage() {
    cat <<'EOF' >&2
Usage:
  script-name.sh [--verbose] [--dry-run] ARG…

Options:
  --verbose     Extra logging
  --dry-run     Print actions without executing
EOF
    exit 2 # '2' because we might exit after successfully checking deps
}

## exit early with all missing dependencies to avoid wasting user time/effort:
require_cmds() {
    local missing=()
    for cmd in "$@"; do
        command -v "$cmd" >/dev/null 2>&1 || missing+=("$cmd")
    done
    if ((${#missing[@]})); then
        echo "Missing required commands: ${missing[*]}" >&2
        exit 1 # '1' because first place we would exit
    fi
}

log() {
    ((VERBOSE)) && echo "$@" >&2
}

########################################
# Argument parsing
########################################

ARGS=()

# simple parsing, no need for getopts
for arg in "$@"; do
    case "$arg" in
        --verbose) VERBOSE=1 ;;
        --dry-run) DRY_RUN=1 ;;
        --help|-h) usage ;;
        --) shift; ARGS+=("$@"); break ;; # safer calls by explicitly separating flags from parameters
        -*) echo "Unknown option: $arg" >&2; usage ;;
        *) ARGS+=("$arg") ;;
    esac
done

if ((${#ARGS[@]} == 0)); then
    usage
fi

########################################
# Main
########################################

require_cmds rsync sed grep

log "Starting script-name.sh"

for item in "${ARGS[@]}"; do
    if ((DRY_RUN)); then
        echo "Would process: $item"
    else
        process_item "$item" || true   # non-fatal
    fi
done

# disable warnings temporarily
set +e
optional_command1
optional_command2
set -e

log "Done."

Haskell

• No GHC warnings: compiles with ghc -Wall -Werror

  • Should be as hlint-clean as possible

• Lists: lists broken over >2 lines should be dangling-comma-prefix style for easier editing, as it makes cleaner line-level diffs and allows adding entries blindly, eg.

  a = [b
     , c
     , d]

• Imports:

  • Enumerated imports: all imports should be fully-enumerated

  • Standard abbreviations: Data.Text is always imported as T, like T.pack:

    import qualified Data.ByteString.Char8 as C8 (...)
    import qualified Data.ByteString.Lazy.Char8 as LBS (...)
    import qualified Data.ByteString.Lazy.UTF8 as U (...)
    
    import qualified Data.Map.Strict as M (...)
    import qualified Data.Set as S (...)
    import qualified Data.Text as T (...)
    import qualified Data.Text.IO as TIO (...)
    import qualified Data.Vector as V (...)
    
    import qualified Debug.Trace as DT (trace)

Renaming

Pages/files should be renamed freely for consistency & convenience.

• File moves: To avoid stale references & 404s, use the gwmv script (in bash.sh) to move a file using git, rewrite all existing hyperlinks, and generate a nginx URL-level redirect.

• Page moves: must be done by hand as gwmv does not yet cover Markdown pages

  • Sub-page moves: to do something like “split out a section to a standalone page” without breaking too many reader experiences, use the redirect-from-id class & data-attribute. (See Lorem Links for live examples, including redirecting multiple legacy IDs.)

    In the simple section case, simply write, for a page /foo:

    # Original Title
    
    [**See main article.**](/bar){.redirect-from-id}

    Now every reader who goes to the URL /foo#original-title will be automatically redirects to /bar. The URL can have an anchor (ie. one could redirect to /bar#baz).

    If the current section’s ID is not the hash-anchor ID which has been broken, the old ID can be specified:

    [**See main article.**](/bar){redirect-from-id="old-id"}

    And since we may want to redirect many IDs, without cluttering the page, it is compatible with the .display-not & .backlink-not classes (since we wouldn’t want to trigger a backlink, as being of no interest to readers of the new page), and we could include some editorial documentation for screen-readers or LLM agents; giving a final link like this, which will “silently redirect” anyone visiting /foo#old-id to /bar:

    [[\[Moved to this article.\]]{.editorial}](/bar){redirect-from-id="old-id" .display-not .backlink-not}

    If it is not appropriate to redirect forcibly, we can eliminate spurious within-page 404s by simply defining an empty span with the mistaken ID at a useful point in the page—possibly setting an ID on the link itself. You can stack multiple empty spans to provide multiple legacy IDs at one location, to catch every possible typo or outdated URL, as file contents may move around multiple times over the decades.

  Prefer Pandoc {#id} on headers/links when a single ID suffices; use <span id="..."> when you need (1) multiple IDs, (2) an anchor mid-paragraph, or (3) to avoid touching surrounding markup.