Terminology and Notation

These rules govern what words, abbreviations, symbols, and technical terms mean on Gwern.net.

• Acronyms/initialisms remove periods, as unnecessary (eg. ‘CIA’, not ‘C​.I​.A​.’; ‘AI’, not ‘A​.I​.’)

  • Personal titles: remove titles like “Mr.”, “Ms.”, “Dr.”, and “Sir” unless the title is itself the subject. While the New York Times may insist on always referring to “Mr. Altman, CEO of OpenAI”, the rest of us find “Altman, CEO of OpenAI” easier to read.

  • Latin abbreviations keep periods (eg. ‘eg.’, ‘ie.’, ‘cf.’, ‘etc.’); do not italicize until a fullblown foreign phrase.

    It’s easier to write without a period, but I find they just look odd that way, because they are not English.

  • Definitions: unusual terms may be bold-defined on first use, Wikipedia-style. For other terms, the popup annotation is considered adequate—a reader unfamiliar with them can simply pop them up and find out. Example: “The National Aeronautics and Space Administration (NASA) is an independent agency…”

• Science:

  • Statistics:

    • “Statistical-significance testing” terminology: always written with a hyphen and ‘statistical’, to emphasize that these technical terms mean far less than they seem, and reduce mistaken interpretations.

      “Type I/II error” is also banned in favor of “false positive/negative”.

    • Latent variables like factors are always capitalized to emphasize that they also do not necessarily reflect the laymen understanding of the word.

      For example, the Big Five personality factor “Conscientiousness”, which is a highly technical and specific measurement with flaws and limitations, is not necessarily what a non-psychometrician understands by the word “conscientiousness”, and it is misleading to write something like “we measure soldiers’ conscientiousness and predict future career success…”

    • Probability confidence terms: try to use the Kesselman estimative words (“certain” • “highly likely” • “likely” • “possible” • “unlikely” • “highly unlikely” • “remote” • “impossible”).

      Our set of estimative words includes the additional “fiction”, “log” (data, experiences, memoirs etc.), “emotional” (feelings, self-expression).

  • Chemistry: chirality is written with smallcaps, eg. the left-handed form of the amino acid theanine is written “l-theanine” (note that ‘l’ is lowercase because uppercase does nothing when smallcaps, ie. <span class="smallcaps">l-</span>).

• Numbers: comma-separated. Especially if they may be confused for a year. Digits are preferred for compactness for numbers >1.

  • Units: prefer compactness, eg. ‘55s’ rather than ‘0m55s’. ‘Approximately’ can be replaced with ‘~’; similarly ‘>’ can replace ‘greater than’, ‘more than’, ‘at least’, ‘higher than’, etc. Do not write out inequalities with HTML entities like > unless writing raw HTML or in a dangerous context.

  • Common unit bases: when mixing units like ‘billions’ or ‘millions’, try to convert them to a common base unit for easier intuitive comparison & subitizing. It is hard to compare ‘$1 trillion’ to ‘$100 million’, but easy to compare ‘$1,000 billion’ to ‘$0.1 billion’.

  • Scientific notation: do not write a number like 1.5e3 except in source code literals; prefer either decimal like ‘1,500’ or full scientific notation like ‘1.5 × 10³’.

  • Poetry: numbers are usually spelled out in poetry; however, we prefer Arabic numerals, mostly to try to avoid line-breaking on narrow smartphone screens.

    Note that they are still considered for all intents & purposes, such as meter, to be equivalent to the written-out form.

• Foreign phrases or words or sentences: italicized using underscores in Gwerndown if not naturalized or familiar to an educated English reader; “tsunami” or “etc.” are not italicized, but “pluralis auctoris” is.

• Dates: dates are written either ‘YYYY-MM-DD’ or ‘Day Month Year’. The former is preferred for data/table/etc., but it can be awkward in prose, where the latter is acceptable. This allows easier machine parsing and eliminates ambiguity.

Prose and Reference Conventions

These rules govern how prose is written, linked, and maintained in source.

• Sentences: single-space after the period, not typewriter double-space.

• Semantic line breaks/“ventilated prose”: paragraphs are separated by double-newlines, and every sentence is separated by a newline. (ie. This is a sentence.\nThis is another sentence in the same paragraph.\n\nThis is a new paragraph.)

  This “ventilated prose” makes it easier to edit & read the Gwerndown source & diffs. This is not enforced due to context-dependence and not wanting to necessarily break at short sentences.

  Note that “ventilated prose” does not mean that every paragraph should be only 1 sentence long. It is purely about Gwerndown source formatting, and should not affect displayed text. It also does not necessarily apply to programming languages. Nor to Gwerndown lists.

• Pluralis auctoris: use “I” when describing something specific that the author did, like running an experiment, unless it was a collaboration, in which case it must be “we”; use a pluralis auctoris “we” when it’s a general discussion the reader is part of.

  For example, “I” run a self-experiment on a drug, but “we” read an excerpted passage from a novel and draw a critical conclusion from it; or in this MoS, I do not expect the reader to agree with many choices, and I implicitly exclude them.

• Profanity: profanity like ‘f—k’ or ‘d—n’ is censored with em-dashes, in keeping with the semi-academic style and because it amuses me to borrow old-timey Victorian writing conventions.

• Ampersand abbreviation: “and” should be abbreviated as “&” for logic disambiguation, where “&” binds more tightly.

• Section cross-references: when linking or citing, the word “Section” is abbreviated with the SECTION SIGN “§”.

• Author links: when linking an author, if available, the preferred canonical URL for them is defined in Config.Metadata.Author.

• Titles:

  • written in title-case

  • annotations: if a paper introduces a new acronym, the full phrase & abbreviation should be used in the title, usually as a prefix, for clarity and search; eg. a paper like “Efficient Reasoning Through Dense Representations” should be retitled “Compressed Chain-of-Thought (CCoT): Efficient Reasoning Through Dense Representations”, so future searches or readers can see that this paper defines “CCoT”. These do not need to be marked with span.editorial.

  The title may also benefit from a short editorial note to disambiguate or include a key term. These do need to be marked with span.editorial.

Essay Metadata

Gwerndown 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, thumbnail-css, created, modified, 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; they should be listed in rough order of creative contribution. A piece overseen by a human should usually list the human first, but if it was fully autonomous, it should put the LLM versions as authors in order of importance and list the human last. (This is because the human must always bear responsibility for publication.)

• 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 • dropcaps-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.; see the more detailed discussion later. 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).

  Note: this optional field can only be used with a valid thumbnail (there is no point styling a thumbnail which doesn’t exist, and that implies an error).

• 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. Video files are not, and third-party MP4s frequently arrive massively over-bitrated; see § Video Recompression for the recipe.

Inline

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

  These are usually written in Gwerndown with the Pandoc long-form ASCII versions like -- or ---, and in HTML (or HTML comments) as Unicode literals.

• 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

  As a personal quirk and artistic flair, I try to vary use of dropcap letters. So 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 Gwerndown 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 Gwerndown 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 a div.smallcaps-not wrapper.

• 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 Gwerndown/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. Single/double/curly quotes are automatically removed from the link target, to allow links like ["foo"](!W) to work as expected without needing to duplicate the text. (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. Raphelson 1980).

  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 Gwerndown syntax for footnotes like [^id]: Content. or ^[Content.].

  The ID should be be usable as a descriptive human-readable HTML ID—a default lowercase (if not proper nouns like names) 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 ≤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 Gwerndown element they are used in, for easier editing. (They are not grouped at the end of the Gwerndown 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.

  In annotations/GTX files, where footnotes are unavailable, brief local editorial updates may remain inline as span.editorial; a single short paragraph is acceptable inline. Collapse only genuine digressions. See Editorial comments.

• 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 Gwerndown bold & italic syntax.

• Abstracts: an abstract is a div.abstract which contains a summary of 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 Gwerndown 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.

  GTXes 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 Gwerndown tables. I usually use either ‘simple’ tables for very simple small tables, or pipe tables for everything else; ‘grid tables’ having proven to be more trouble than they are worth despite an Emacs mode. Default to pipe tables for their greater robustness to future modifications. (If one finds oneself ever rejiggering the whitespace in a simple table, it is past time to move to a pipe table.)

  Ideally, all tables would be recreated in pure Gwerndown, 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 Gwerndown.)

  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 written 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 Contents, or we have already gone uncomfortably deep, like 7-level deep.

  Horizontal rulers sometimes are customized per-page.

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>
```

​title: "TITLE"
​author: Gwern
​description: "1–3 sentence blurb (20–650 chars)."
​created: YYYY-MM-DD
​modified: YYYY-MM-DD
​thumbnail: /doc/PATH/TO/IMAGE.jpg
​thumbnail-text: "‘THUMBNAIL TITLE’: Thumbnail/preview caption. (Reuse verbatim if the same image is appended full-width.)"
​thumbnail-css: invert-not outline-not # optional
​status: finished
​confidence: fiction
​importance: 4
​css-extension: dropcaps-not reader-mode toc-not index # TODO: consider `poem-mode` shortcut
...

<!--
COMMENTARY (optional; can be long):

STRUCTURE AND FORM:
- ...

KEY FORMAL TECHNIQUES:
- ...

THEMES / ALLUSIONS:
- ...

NOTES:
- If you deliberately violate a global MoS rule (spelling/diction/typo/etc.), document it inline on the relevant line.
-->

Optional abstract:

<div class="abstract reader-mode-not">
> 1st paragraph: hook + 1–2 sentence summary of what the poem is doing.
>
> 2nd paragraph: formal notes (meter/rhyme/refrain), setting, and/or what to look for.
>
> 3rd paragraph (optional): variants / colophon / why reader-mode is enabled / what is hidden in collapses.
</div>

<!-- Optional FORM / ARGUMENT ARC / SCANSION KEY (recommended for brittle form or LLM-heavy revision) -->

<!--
FORM
...
-->

<!--
ARGUMENT ARC
...
-->

<!--
SCANSION KEY
...
-->

<div class="poem" id="poem-main">
<!-- STANZA 1 (L1–4, pattern): job=...; domain=...; tone=...; structural-enjamb=...; anchor-rhymes=... -->
<!-- L1 METER: land=...; role=...; enjamb=(none|→L2) -->
First line of poem. <!-- 10: SCAN1 sion2 GO3 es4 HERE5. [rhyme/rhyme@N] --> \
Second line; comment must come before the backslash. \

New stanza starts after a single blank line. \

Use an indented half-line break with " / " (space-slash-space): \
So much / depends upon \

Use caesura marks with " || " (space-double-pipe-space): \
In they hacked them, || out they hurled them, \
</div>

<!-- OPTIONAL: stanza/section separator without a header -->
---

<!-- OPTIONAL: hardwire the icon (eg. “sun” / Vergina sun) -->
<div class="horizontal-rule-nth-1"><hr></div> <!-- sun -->

<!-- OPTIONAL: inter-poem headings / stage directions between multiple poem blocks -->
<div class="text-center">[I. SECTION TITLE.]</div>

<div class="poem" id="poem-2">
Second poem / section goes here. \
</div>

<!-- OPTIONAL: illustration (often reuse `thumbnail` + `thumbnail-text`) -->
![](/doc/PATH/TO/IMAGE.jpg "‘THUMBNAIL TITLE’: Thumbnail/preview caption."){.invert-not .width-full}

<!-- OPTIONAL: multiple illustrations, randomized (show one per page load) -->
<div class="display-random-1">
  <div class="display-entry">
  ![](/doc/PATH/TO/IMAGE-1.jpg "…"){.width-full .invert-not}
  </div>

  <div class="display-entry">
  ![](/doc/PATH/TO/IMAGE-2.jpg "…"){.width-full .invert-not}
  </div>
</div>

<!-- OPTIONAL: variants / appendix / alternate form (collapsed by default) -->
<div class="collapse" id="variant-1">
<div class="abstract-collapse">
> Variant: one-line description (eg. “Alternate version: Pindaric ode (unedited).”)
</div>

<div class="poem" id="poem-variant-1">
Variant text goes here. \
</div>
</div>

<!-- OPTIONAL: exact-whitespace concrete poetry -->
~~~{=HTML}
<pre class="poem-html" id="poem-html-1">
Exact whitespace here (Pandoc-safe raw HTML block).
</pre>
~~~

<!-- OPTIONAL: colophon / acknowledgments / discussion (collapsed) -->
<div class="collapse editorial" id="colophon">
[Colophon.]{.marginnote .abstract-collapse} By …

Full colophon / acknowledgments / discussion text here.
</div>

<!-- OPTIONAL: if you want normal link styling after the poem despite `reader-mode` -->
<span class="reader-mode-disable-when-here"></span>

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.

• Trusted-only: Bash is notoriously impossible to secure, as just correct handling of all possible filenames is shockingly difficult, and there are many “convenient” footguns, as Shellshock demonstrated.

  So Bash scripts should only be used by a trusted user on safe inputs (ie. arguments like filenames). Any other use-case should be immediately rewritten in a safe language like Python or Haskell.

• 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.

  • File redirection clobbering has been disabled for safety (set -o noclobber); if you want to overwrite a file with >, you must explicitly rm it first.

• 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.)

  • Clear control flow: prefer left-to-right pipelines for readability.

    I deliberately tolerate the “useless use of cat” (UUOC) idiom in maintenance-heavy code. The efficiency cost is usually negligible, while the readability gain is concrete: cat foo | ... | bar puts the input where the eye expects it and keeps every stage in the same shape, stdin → stdout.

    UUOC also makes edits simpler: prepend preprocessing, concatenate multiple inputs (cat a b c | ...), or expand globs (cat *.txt | ...) without restructuring the command.

    Do not “fix” UUOC unless cat is a measured bottleneck, the command is in a hot loop, or the pipeline is clearer without it.

• 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 and 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
########################################

. ./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
ARGS=()

while (($#)); do
    case "$1" in
        --verbose) VERBOSE=1; shift ;;
        --dry-run) DRY_RUN=1; shift ;;
        --help|-h) usage ;;
        --) shift; ARGS+=("$@"); break ;;
        -*) echo "Unknown option: $1" >&2; usage ;;
        *) ARGS+=("$1"); shift ;;
    esac
done

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

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

require_cmds rsync sed grep

log "Starting script-name.sh"

process_item() {
    local item="$1"

    : # TODO: implement
}
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; current qualified-import abbreviation include:

    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)

  • Import module order: base/system/universal ‘default’ packages (eg. Data.List), non-default libraries (eg. Text.Pandoc), internal library/executable modules (eg. for Gwern.net code, LinkMetadata), config modules (eg. Config.InterWiki); default alphabetical order

• Comments: comment blocks >10 lines should always be in bracket syntax {- ... -} rather than double-dash syntax.

• Type signatures: written compactly on a single line if possible, otherwise line-broken & indented; the order of imports should be: functions, types, operators; default alphabetical order.

  Related declarations with the same type should be grouped & merged into one type signature, like a, b, c :: String.

Renaming

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

• File moves: To avoid stale references and 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 Gwerndown 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 and 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 (as a data-attribute):

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

    And since we may want to redirect multiple IDs, without cluttering the page, it is compatible with the .display-not and .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.

Paths vs Display Names vs Aliases

There are three names:

1. canonical path: the filesystem/tag identity, eg. ai/nn/transformer/gpt/4-5;

2. display name: the human-facing label, eg. GPT-4.5;

3. aliases: accepted input forms, eg. gpt-4.5, gpt45, 45.

Never store a display name or alias where a canonical path is required.

Path Syntax

• Lowercase ASCII, hyphen-separated, slash-delimited: ai/nn/transformer/gpt/4-5.

  No underscores, spaces, CamelCase, or Unicode. The implementation accepts a wider character set for legacy/domain tags; the authoring policy is stricter.

  • No periods in paths: version numbers, decimals, and anything else that would contain a . hyphenate instead (gpt/4-5, not gpt/4.5).

    Periods are reserved for actual filenames (2023-mihara.pdf) and preserved in URL-style tags that are domain names (fiction/humor/comics/hardtruthsfromsoftcats.tumblr.com, or to avoid colliding with mirrors like Rotten.com).

• Multi-word components hyphenate: mixture-of-experts, public-domain-review, self-sinking, darknet-market.

• Singular by default: dog not dogs, ant not ants, nootropic not nootropics, cellular-automaton not cellular-automata.

  Plurals and alternate forms live in the alias table (§ Aliases and Typo Tolerance), not in the canonical path. (The exception is referents that are intrinsically plural: sociology/small-groups/quakers.)

• Wide, not deep: prefer flat hierarchies.

  Create a tag when there are ≥3 likely entries, a stable transclusion target, or an unusually important concept. Refactor a tag when it approaches 50–100 entries, when its contents visibly split into repeated clusters, or when frequent co-tags suggest a latent subtopic.

  Depth is unbounded in principle (<7 levels exist in practice, eg. ai/nn/diffusion/midjourney/dropcap/dropcat), but add depth only when a subtree has enough material to justify its own index page.

• Tag resolution: Resolution order is permissive for humans, not a license for automation.

  Interactive CLI use may rely on aliases, suffixes, and edit-distance guesses. Bulk edits and LLM outputs must emit canonical paths only. Ambiguous short forms should be expanded by table lookup, not guessed.

  Examples: chess resolves to reinforcement-learning/chess, even though psychology/chess also exists. lsd resolves to psychedelic/lsd, even though nootropic/lsd and darknet-market/silk-road/1/lsd exist. safety resolves to reinforcement-learning/safe, not generic safety.

  • good: genetics/heritable/correlation/mendelian-randomization; bad: mr

  • good: ai/nn/transformer/gpt/4/poetry; bad: gpt4/poetry

  • good: design/typography/tex; bad: latex

Display Names

Display names are derived, not always explicitly stored. A canonical path may have an explicit tagsLong2Short display override; otherwise it is displayed after regex-level rewrites, and finally by the raw path/name. Do not infer canonical tags from display names by hand; use the resolver/table.

Paths appear in URLs and the filesystem; display names appear in popups, similar-links, and the tag-index listing.

• 1–3 words: lowercase for common nouns (cloning, meditation, forecasting), capitalized for proper nouns (Bitcoin, Japan, Borges, DeepSeek, Anthropic).

• Italicize titles of works via <em>…</em>: <em>Dune</em>, <em>My Little Pony</em>, <em>Portia</em> spider, <em>NGE</em>.

• Standard acronyms replace the full form: AI, CS, IQ, RL, DNB, DNMs, x-risk, VR, MARL, SCZ, TBI.

  Acronyms stay in regular caps rather than smallcaps, because tags render italicized and Source Serif Pro lacks italic smallcaps.

• Curly apostrophes only: Algernon’s Law, Alzheimer’s, Metcalfe’s Law.

  The canonical path drops the apostrophe (psychiatry/alzheimers); the display name restores it.

• Parenthetical disambiguators, when actually needed: magnesium (nootropic), aspirin (aging), Clippy (AI safety), <em>Nadia</em> (anime).

  Recurring disambiguators: (AI), (cat), (typography), (aging), (psych), (anime), (novel), (story), (DNM), (LSD), (BPD), (breeding), (chemistry), (cryptography), (fraud). Add one only when the bare display name would collide or be genuinely opaque in popup context; never prophylactically.

• Richer HTML, sparingly: narrow typographic cases like design/typography/tex → <span class="logotype-tex">T<sub>e</sub>X</span> and co2 → CO<sub>2</sub>. Avoid inventing new ones.

• Source order: deeper paths before their parents: tagsLong2Short is processed first-match-wins after reverse. This is what lets ai/nn/transformer/gpt/4/poetry display as GPT-4 poetry while ai/nn/transformer/gpt/poetry displays as GPT poetry.

• Global rewrites via regex: wholeTagRewritesRegexes handles rewrites too broad for the explicit table.

  Uppercasing acronym segments (^cs/ → CS/, ^ai/ → AI/, ^iq/ → IQ/), subtree-level renames (^psychology/ → psych/, ^technology/ → tech/), and a few italic injections (^anime/eva$ → <em>NGE</em>). Use the regex layer only when the alternative is one explicit entry per descendant.

Hierarchy & Placement

• Path children must narrow the parent under the parent’s frame. A child may be a subtype, method, object, dataset, author, work, drug, organism, project, or special case. It must answer “why is this here rather than elsewhere?” but need not satisfy a strict “X is-a Y” test.

  ai/nn/gan/stylegan/progan reads as “ProGAN, a kind of StyleGAN, a kind of GAN, a kind of NN, a kind of AI”. If a sub-tag isn’t a kind-of the parent, it doesn’t belong under the parent.

• Frame of analysis beats nominal object: animal behavior goes to psychology/animal/, not biology/animal/, because the content is about psychology using animals as subjects.

• Interest-driven placement, not perfect ontology: a topic goes where it was first written about from the angle it was written about.

  Chess has no top-level chess/ tag: the site writes about chess as an RL testbed (reinforcement-learning/chess) and as a cognitive-psychology testbed (psychology/chess), not about chess-the-game per se. Parallel cases: aging clocks at longevity/epigenetics not genetics/epigenetics; natural language at psychology/linguistics rather than a standalone linguistics/; psychedelic at top level rather than under psychiatry/.

• Match existing placement when in doubt: mimic where similar material already lives, instead of inventing a cleaner parallel hierarchy.

• One canonical home per sense/frame, not one tag per URL.

  A URL may have multiple tags when it belongs to multiple independent frames. But do not tag both a parent and its child; use the child only.

• Prefer existing top-levels: the ~65 substantive top-levels (ai, psychology, reinforcement-learning, statistics, cs, psychiatry, genetics, fiction, darknet-market, cat, longevity, economics, design, anime, nootropic, sociology, philosophy, technology, iq, japan) absorb most additions. A new top-level is warranted only when a topic is orthogonal to all of them and already has several documents in hand.

  Gwern.net has many minor/grandfathered/project roots, but new material should normally be absorbed into the core roots unless it clearly belongs to an existing minor root or already justifies a new root.

Tag Lifecycle

• When to create: enough material exists to populate a page (typically ≥3 documents), or the tag is needed as a stable transclusion target (darknet-market/dnm-archive and ai/anime/danbooru exist partly to be transcluded into dataset-usage sections). A one-document tag with no prospects is clutter.

• abstract.md, optional: a tag directory may contain an abstract.md, a tag-page preface hook providing hand-written framing above the auto-generated listing. It is transcluded at the top of tag-directory pages, and may itself transclude another page or page section.

  Worth writing when the topic has key historical background a cold reader won’t have (ai/nn/transformer/gpt/inner-monologue, ai/nn/dynamic-evaluation), or when the tag name is a nonstandard coinage that needs defining before the listing makes sense (psychology/dark-knowledge, psychology/cognitive-bias/illusion-of-depth). An abstract.md that just restates the tag name is worse than none.

• Renaming: reluctantly: renaming breaks URLs, backlinks, similar-link neighborhoods, nginx redirects, and the rewrite tables. Prefer, in order: add an alias in tagsShort2LongRewrites; change the display name in tagsLong2Short; add a regex in wholeTagRewritesRegexes.

• When renaming is unavoidable: add the old path as an alias → the new path; add an nginx redirect so external links survive; keep the old entry indefinitely as a fossil. The regex fossils ^genetics/selection$ → evolution and ^artificial/selection$ → genetics/selection/artificial record past renames of this kind.

Aliases and Typo Tolerance

Any string a reader or author might plausibly type for a canonical tag, and which doesn’t match a canonical path, goes in tagsShort2LongRewrites. The table grows freely and currently mixes 4 jobs:

• Abbreviations and synonyms: mr → genetics/heritable/correlation/mendelian-randomization; moe → ai/scaling/mixture-of-experts; xrisk → existential-risk; sr1 → darknet-market/silk-road/1; bash → shell.

• Alternate spellings: anaesthesia → anesthesia; quantised → ai/nn/sparsity/low-precision; javascript → js.

• Morphology: dogs → dog; ants → ant; the full psychopath/psychopathic/sociopath/sociopathy/sociopathic family → psychology/personality/psychopathy.

• Typos: algoprithm, narcisism/narcississm/narcisisst, desing, eamcs, wrtigin, and ~40 variant misspellings of anencephaly accumulated from real autocomplete events. No editorial shame—documenting a typo once beats hand-fixing it repeatedly.

Two conventions:

• Seed aliases when creating a new tag: the bare last path component, any acronym, plurals, and any word with a known frequent misspelling.

• shortTagBlacklist: strings too common-English or too syntactic to be meaningful guesses—a, the, of, it, is, git, rm, sed, <p>, <ul>, etc.

  These throw an error rather than silently guessing, because any match from such a generic string is more likely a caller bug than a genuine lookup. Prefer adding a specific alias to tagsShort2LongRewrites over relying on the resolver’s edit distance fallback, which is a safety net for unpredictable typos in interactive use rather than an intended lookup path for bulk or automated use.

Cross-References To Existing Manual of Style Sections

This section covers the esthetic and UX layer; the Gwerndown writing conventions for these features live in the existing Manual of Style above. When in doubt, the writing-convention section is authoritative for syntax; this section is authoritative for visual treatment.

• Math. For Gwerndown conventions ($…$ vs $$…$$, escaping, numbering), see § Math. Esthetically: prefer Unicode glyphs (‘σ’, ‘√’, ‘≤’, ‘×’) for inline single symbols; use MathJax only when the expression is multi-symbol, requires alignment, or contains super/subscript stacks.

• Code blocks & syntax highlighting. For language tags, indentation, and inline-code conventions, see § Code. Esthetically: monochrome code blocks by default; the syntax-highlight palette is intentionally muted so code does not dominate the page.

• Transclusion. For .include, .include-strict, and .include-block-context semantics, see § Transclusion. Esthetically: a transclusion is invisible when it succeeds; the host page must read identically whether the included content is fetched live or hand-pasted.

• URLs & file-naming. For the /doc/ taxonomy, slug conventions, and the YYYY-MM-DD-author-… filename pattern, see § URLs. The esthetic corollary: URLs are part of the design surface; an ugly URL is a bug.

• Abstracts & epigraphs. For <div class="abstract"> wrapping a <blockquote>, <div class="epigraph">, and the placement rules, see § Abstracts. Esthetically: the abstract gets a thin grey border, a subtle off-white background, and slightly tighter measure (--GW-abstract-*); the epigraph gets italic + right-aligned attribution.

• Inflation-adjustment. For the .inflation-adjusted mechanism and implicit-year inference, see § Currency/Inflation. Esthetically: the adjusted figure displays in the body, with the original parenthesized in smallcaps via JS; do not hand-author the parenthetical.

• Admonitions / callouts. Used sparingly: a real warning, a real aside, a real tip. For syntax and the current set (with iconography from the link-icon sprite), see § Admonitions. Esthetically: admonitions are earned signals; use them sparingly, and if the same admonition keeps appearing, either the underlying claim belongs in the body text or the admonition type is being overused and should be downgraded to normal prose.

Esthetic Stance

The overall visual target is a “classic style” of web design: a monochrome, high-contrast, book-like page that foregrounds the text and hides everything else until asked for. The reference points are not other blogs but rather Edward Tufte’s books, a well-set scholarly monograph, and the older hypertext systems (Xanadu, MediaWiki, HyperTIES, GNU Info, Everything2, and the Symbolics Document Examiner) which Gwern.net tries to realize in HTML. Social-media conventions (gradient backgrounds, cards with drop-shadows, avatar rows, “like” counts, call-to-action buttons, emoji bullets, mid-article newsletter pop-overs, cookie banners, animated hero images) are forbidden; they signal low-commitment ephemeral content, the exact opposite of the site’s “Long Content” goal.

This is not minimalism in the impoverished sense. Gwern.net is loaded with features: sidenotes, link-icons, dropcaps, smallcaps, transclusion, popups, backlinks, similar-links, inflation-adjustment, admonitions, collapses, margin notes, carousels, custom syntax-highlighting, dropcap sets, holiday themes, reader-mode, dark-mode. The discipline is that each feature must be earned by readability gain, not added for decoration (with occasional exceptions)⁶, and must stay out of the reader’s way until they want it. “Minimalist” here means parsimonious, not simple-minded.

Three related attitudes fall out of this:

1. Prefer Unicode and CSS over images or JS. A MULTIPLICATION SIGN × beats an SVG “×”; a <span class="smallcaps"> beats a photo of small caps; a CSS-drawn quotation-mark beats an image. Reserve images and JS for cases where text cannot do the job.

2. Prefer earned flourishes over default flourishes. A feature used everywhere (eg. a gradient, a rounded card) stops meaning anything; a feature used only when it helps (a dropcap on the first paragraph, smallcaps for l-theanine, an admonition for a genuine warning) carries signal.

3. Prefer the oldest solution that still works. Progressive-enhancement, server-side includes, plain <a>+<img>, @media print, system-font fallbacks, font-display: swap—these have outlasted every JavaScript framework generation and will outlast the current one.

Typography

Typography is the core of the site; everything else is applied to surfaces defined by it. Treat changes to type as load-bearing architectural edits and not style tweaks.

Color

Gwern.net is monochrome at rest. The light-mode palette for ordinary prose and ordinary UI is black (#000), white (#fff), and ≈25 grays between. There is no brand color, no accent color, no “primary” color in body text or chrome.

Non-gray color is reserved for semantic state—color signals something, it does not decorate:

• the “skip to content” accessibility link (--GW-skip-to-content-background-color: #bf1722);

• syntax-highlighting in code blocks (a deliberately muted, multi-hue palette defined in colors.css);

• table-sort state (the sorted-column heading highlight --GW-table-sorted-column-heading-background-color: #8bd0ed) and table row/column hover highlighting;

• code-line highlighting (for author-annotated lines in a code block);

• light/dark-mode correction filters and literals in light-mode-adjustments.css and dark-mode-adjustments.css where the automatic palette or inversion misfires;

• link-activation color (hover/focus): tinted by destination per /red and /web-color.

Do not add a new color outside these categories without a written rationale; see /red for the reasoning about colored links specifically.

--GW-body-background-color:       #fff;
--GW-body-text-color:             #000;
--GW-body-link-color:             #333;
--GW-body-link-hover-color:       #888;
--GW-body-link-visited-color:     #666;
--GW-blockquote-border-color-level-one:   #ccc;
--GW-blockquote-border-color-level-two:   #c4c4c4;
--GW-TOC-background-color:        #f8f8f8;
--GW-abstract-border-color:       #bbb;

Figures

Gwern.net distinguishes 3 kinds of figure, each with its own conventions and its own subsection below:

1. Images proper—photographs, paintings, screenshots, diagrams lifted from papers. Discussed under § Images & Inversion.

2. Graphs & data-visualization—statistical plots, schematic figures, anything the author generated from data. Discussed under § Graphs & Data Visualization.

3. Hero / illustrative thumbnails—the single per-essay image declared in YAML front-matter. Discussed under § Hero & Illustrative Images.

The shared rules apply to new or touched figures; legacy figures are not required to be mechanically rewritten:

• Every new figure lives in a <figure> with a <figcaption> that is complete enough to be read aloud. The caption is not a restatement of the image; it is what the reader of 2040 needs to reconstruct the image’s point after the file rots.

• Every raster figure ships at ≥2× its display size to survive HiDPI displays.

• Mark .invert / .invert-not and .outline / .outline-not explicitly when the auto-classifier’s guess is non-obvious; the defaults (auto-invert via the classifier, default outline) are fine when they are obviously right. See § Images & Inversion.

• Every figure has a descriptive filename in the site-wide convention: YYYY-MM-DD-[author]-[source+version]-[description].[ext]. plot1.png, hero.jpg, and image (3).png are regressions.

• Content figures should be stored under /doc/<topic-path>/ matching their subject taxonomy; site chrome, fallbacks, and UI assets may live under /static/.

• No WebP/AVIF in content raster images. Support would add polyfill/branching complexity, CLI/tooling support remains worse than JPG/PNG/SVG, lossy re-encoding creates churn, and the compression win is not worth the pipeline complexity. Inputs in those formats are converted at ingest.

  (The infrastructure may recognize legacy or auxiliary formats for link-icons, thumbnails, or old files; recognition is not authoring permission.)

Tables

Tables are part of § Figures; they are quantitative figures made of text, and the same Tufte/Bringhurst discipline applies—maximize data-ink, minimize chartjunk, defer to the reader.

Mechanics:

• Pipe-tables, almost always. Gwerndown grid-tables are too brittle to author and to round-trip through edits; pipe-tables are the default. If a cell seems to need internal newlines, first try <br>, a shorter caption, a collapse, raw HTML, or a transcluded annotation. Grid-tables are a last resort and should be justified with an HTML comment.

• Captions go below the table. Pandoc renders Gwerndown table captions in a <caption> placed below by default; this is the convention to keep. The caption is the table’s title, source, and unit-of-observation note in one—write it like a Tufte figure caption, not a heading.

• Column alignment is meaningful, not decorative. Pandoc Gwerndown lets you align columns left/center/right via the :---, :---:, ---: syntax; use it. Numeric columns right-align; short categorical labels center; prose left-aligns. A misaligned numeric column is a readability bug, not a style preference.

• Headers are short, plain Roman text. No smallcaps rule for headers; just emphasize short labels so the column doesn’t either become absurdly wide or break across two lines. If the natural label is long, abbreviate in the header and explain in the caption.

• Top and bottom rules; light row-striping. The site uses a Tufte-style top-and-bottom horizontal rule with a thin header rule, plus light zebra-striping for scanability across many rows; the relevant variables live under --GW-table-*. Do not add internal vertical rules.

• Sortable columns are free. The frontend wraps every table in tablesorter (third-party JS, largely unmodified), so any column header is click-to-sort by default. The sorted-column heading uses a distinct background (--GW-table-sorted-column-heading-background-color); do not override it locally. If a specific table genuinely should not be sortable (eg. where row order carries meaning the sort would destroy), suppress it at table level with .table-sort-not.

• Wide tables. A genuinely wide table can use .width-full to break the column constraint, the same as a wide plot. A very large table has several options: leave it visible; move it to its own appendix section; wrap it in a div.collapse; or park it in an annotation and transclude it inside a collapse on the host page. The right call depends on how central the data is to the argument and how badly hundreds of rows displace the body text—none of these is required.

• When not to use a table. Two columns where one is a label and the other is a definition: that’s a list, not a table. A single column of bullets dressed up with borders: that’s a list—and if that list would render as a long tall strip, add class="columns" to the enclosing element to wrap it into multiple CSS columns. A table is for ≥2 dimensions of comparable data; otherwise prose or a list reads better.

UI Text Conventions

Text added by the site’s UI code (rather than the author’s Gwerndown) is visually marked with square brackets, as a signal that the reader can ignore it if they are reading linearly and a handle if they want to interact. Examples: [click to uncollapse], [click to expand], [see backlinks], [popover], [details], [×] on a dismiss widget. This is the editorial convention for insertions, analogous to how square brackets mark editorial interpolations in scholarly quotation ([sic], [emphasis added]). The bracketed text is typeset in the UI sans-font and is excluded from copy-paste by user-select: none on the wrapper. Do not use parentheses or italics for this role; parentheses belong to the author, italics belong to emphasis.

Iconography & Link Decoration

Links are decorated—but decorated semantically, not decoratively. The 3 primary link decorations are:

1. Underline. Running-text links are underlined by default; the underline is a link’s most accessibility-robust affordance. See Nielsen’s 1997_29ya “Guidelines for Multimedia on the Web” and the follow-up “Guidelines for Visualizing Links” (2004_22ya); the underlying ergonomic argument has not aged. text-decoration: underline with a non-default text-underline-offset for serif readability. Disable the underline only for specific in-UI cases (icon-only controls, the ToC, nav chrome, reader-mode’s stripped rendering); never for running-text links.

2. Link icons (data-link-icon/data-link-icon-type attributes), small glyphs appended to links, indicating the kind of destination (Wikipedia article, Arxiv paper, PDF, YouTube video, Twitter thread, Substack post, …). The icon set lives in /static/img/icon/; new icons are added there as stand-alone SVGs, subsetted into the single composite icons.svg sprite by the build step. Do not embed a new icon inline in CSS or HTML; route it through the icon build so it gets the sprite treatment, link-icon-type machinery, and dark-mode inversion automatically. Link-icon classification happens at Haskell build time using URL patterns; the resulting data-link-icon / data-link-icon-type attributes are then rendered by the CSS with no runtime regex on the browser side. The older CSS-regex approach, which classified at render-time in the browser, is explicitly graveyarded; build-time classification is faster, more correct, and more maintainable.

3. Popups/popovers. See § Interaction: Popups, Popovers, Collapses. The hover/focus affordance is itself a form of decoration, signaling “there is more here” without a visible mark.

Links are monochrome in their rest state (--GW-body-link-color #333, a dark gray distinguishable from body text #000). On hover or focus, however, a link is rubricated: tinted with a color keyed to the destination—typically the destination site’s predominant brand color, or a standardized association (eg. PDF links go red, Wikipedia links go black-on-grey, Arxiv links a dark red, etc.). This is automated from the URL at build-time, not hand-authored per link. The affordance stack is thus: underline carries “this is a link”; link-icon carries “this is what kind of link”; hover-color carries “this is where it will take you”; and the rest state remains monochrome so a page at rest reads as a book page, not a web page. See /red: “Website Colors: Red vs Blue” and /web-color for the full treatment and the per-site color assignments. Visited links are --GW-body-link-visited-color (#666); do not hand-override.

Layout & Rhythm

The page is single-column on narrow viewports and “body column + margins” on wide ones; margins host sidenotes, margin notes, dropcap ornaments, and nothing else. There is no content sidebar on ordinary essay pages; the table of contents floats left of the article on wide screens and becomes inline on smaller screens, auxiliary navigation rather than a content column. The footer is minimal—typically the site-logo plus occasional rotating elements (blogroll teaser, quote-of-the-day, footer link-of-the-day, legal line)—but the specifics are page-class dependent; the binding rule is that the footer does not compete with the body text for attention.

Vertical rhythm is set by the leading and the paragraph indent; there are no oversized hero headings. <h1> is the page title and never appears twice; <h2>–<h6> use increasingly subtle distinction (size, weight, case (eg. all-uppercase or smallcaps at certain levels), border, spacing) rather than color. --GW-H1-border-color and --GW-H2-border-color (both #888) provide the thin under-rule on the top 2 heading levels; lower levels are distinguished by weight and smallcaps, not rules.

Two layout patterns deserve special mention:

• Sidenotes/footnotes are the same element. Write a Pandoc footnote ([^id]: …); the JS will render it as a sidenote in the right margin on wide viewports and as a footnote at page bottom on narrow ones. Do not hand-author <aside> sidenotes; the responsive switch is automatic and correct.

• Margin notes (span.marginnote) are not sidenotes: they are 1–3 word summaries of a paragraph, rendered in the left margin, ideally collected into a micro-ToC at the start of the section. They are the visible “outline” of a long essay, and they are what makes the “iceberg” of a dense page navigable. Do not use them for asides or jokes; those go in footnotes or collapses.

Interaction: Popups, Popovers, Collapses

The signature interaction of Gwern.net is a 3-tier disclosure system—popup, popover, collapse—that lets a page hold an iceberg of references while still being readable top-to-bottom. You will break the site if you invent a 4^th.

• Popups: a hover-triggered floating preview of a link’s annotation or target, on devices with a mouse. Powered by popups.js and its data source, the annotation database (see GTX.hs). Style variables live under --GW-popups-popup-*. A popup’s contents are themselves ordinary Gwern.net HTML, so they can contain images, sidenotes, math, code, even nested popups—no special “popup mode”. Popup title-bars carry alternate links in bracketed small-caps format—eg. [ARCHIVE] (the Internet Archive/local mirror of the linked resource), [HTML] (a mobile-friendly live HTML rendering of a PDF or scanned document)—as part of the popup chrome. These are a concrete UI expression of the “local > remote” principle and the mobile-reading priority: they should stay short, bracketed, visually secondary to the canonical title/fulltext link, and use the same [text]-bracket convention as other editorial UI affordances (see § UI Text Conventions).

• Popovers: the touch/mobile counterpart of popups: a screen-level preview interface rather than a hover floating window. Powered by popovers.js (filename not yet renamed to match the reader-facing term). Variables under --GW-popovers-popover-*. A link that works as a popup on desktop works as a popover on mobile, from the same HTML; the responsive switch is in the JS, not the markup.

• Collapses: a click-triggered in-page expansion. The element is div.collapse/span.collapse, not <details>—which we rejected for insufficient control over animation, styling, and keyboard behavior. Almost any block or inline element can be collapsed: sections, blockquotes, figures, tables, code blocks, lists, and entire appendixes. When collapsed, the element may show a preview via .abstract-collapse (kept visible when expanded) or .abstract-collapse-only (shown only while collapsed), useful when a collapse needs an editorial summary rather than a mechanical first-line preview.

Annotation/popup behavior on a specific link is suppressed with .link-annotated-not (no annotation fetch) or .link-live-not (no live-link proxy); at page scope use the extract-not page-level CSS extension. Backlinks are suppressed with .backlink-not; link-icons with .icon-not. The big-endian naming means these are discoverable by tab-completion: type .link- and see everything link-related.

Do not bind new interactions to hover without a focus-equivalent; keyboard users and touch users exist. Popups have an intentional 750 ms hover trigger delay (Popups.popupTriggerDelay, with popupFadeoutDelay: 100 and popupFadeoutDuration: 250 on dismissal); a faster delay produces a “trail of popups” effect when the mouse passes over many links en route to its target, which is intolerable. The number was tuned empirically; do not lower it without re-running that empiricism. Do not layer popups >2 deep visually, even though the system allows arbitrary nesting—a chain of previews beyond 2 is harder to read than just clicking through.

Reader Mode & The Toolbar

Reader mode strips visual noise: underline decoration on in-body links, dropcaps, smallcaps first-line, link-icons, and sidenote hover effects. It is intended for artistic pages (poetry, fiction) and for readers who find the default too busy. A page may default to reader mode with css-extension: reader-mode when focus or hiddenness are desirable (eg. a story or poem should be glossed only after reading it unmediated); hide a specific element while in reader mode with .reader-mode-not; disable reader-mode at a specific point with <span class="reader-mode-disable-when-here"></span>. The toolbar reader-mode preference is currently sticky site-wide; issue #42 tracks switching it to per-page/per-URL state.

The floating toolbar in the corner holds the mode toggles (dark/light/auto, reader-mode on/off/auto, popups on/off, theme-reset) and the search widget. Toolbar icons come from the same sprite as link-icons. Do not add a new toolbar control lightly; every control is visual clutter paid by every reader on every page. A candidate control should be on more essays than not, or it does not belong.

Demo-mode addresses the discoverability-vs-hiding tradeoff. Because Gwern.net hides most of its affordances (no persistent sidebar, no always-visible “share”/“subscribe”/“related” rails), a first-time visitor can miss them entirely. Demo-mode is a developer opt-in, first-visit/use-count bootstrap: selected controls may briefly become more obvious, then retire after the reader has seen or used them. The general pattern is “powerful features are hidden, but discoverability is bootstrapped once and then fades”; when adding a new toolbar control, consider whether it needs a demo-mode beat, and whether the demo-mode tour is getting too long to reasonably land on every first-time reader.

Reader-mode state, dark-mode state, popup preference, and demo-mode state persist via localStorage; an in-page control must write its state there or it is incomplete.

Accessibility

Accessibility is not a compliance checklist; it is a corollary of the progressive-enhancement principle. The core text of a Gwern.net page should remain readable under adverse conditions: a screen reader, a text-file dump of the HTML, the raw Gwerndown source. Lo-fi browsers (eg. eww, elinks, Lynx, Dillo) generally cope with the initial HTML render, but the increasing use of client-side transclusion means that backlinks, similar-links, link-bibliographies, and other JS-injected content will be missing for any browser that does not execute the page’s JS. That tradeoff is accepted deliberately, not by accident: core prose must degrade gracefully, enrichments may not. If the core prose is broken in a non-JS environment, the HTML is wrong, not the reader.

Concrete rules:

• No-JS degradation. Core host-page prose should be present in the initial HTML. Major JS-gated enrichments should degrade harmlessly or show a concise <noscript> warning; transcluded pages and generated aux-link sections may be incomplete without JS by design.

• “Skip to content.” The first interactive element on every page is <a id="skip-to-content-link" href="#markdownBody">. Its styling lives under --GW-skip-to-content-*; background-color: #bf1722 is the skip-link red in ordinary navigation chrome, chosen for high contrast against black text regardless of mode; other reds exist for semantic state such as syntax highlighting, errors, and destination-specific hover states. Do not remove, hide, or reposition this link.

• Focus states. Every clickable or hoverable element must have a keyboard-focus state. This is load-bearing for non-mouse users; the site-wide :focus-visible outline should be preserved.

• Alt-text. New images should include useful alt where it adds information beyond the caption; it may be omitted on purely decorative figures (eg. an illustration appended to a poem). Thousands of legacy images do not have alt-text, and the MoS explicitly tolerates the resulting validator warnings; this is a standing task, slowly being filled in by LLM-assisted annotation. Do not mechanically rewrite legacy images, but do not ship new information-bearing images without useful alt text, a useful caption, or equivalent thumbnail/provenance text.

• Semantic HTML where Gwern.net already uses it. Use <figure>/<figcaption>, <blockquote>, headings, and tables as Pandoc emits them; a <div class="figure"> where a <figure> would do is a regression. For site-specific UI primitives, however, prefer the established big-endian <div>/<span> class system over native HTML whose behavior cannot be fully controlled: <details> is rejected in favor of div.collapse, <abbr> is not used, and the HTML5 native popover attribute is not used (we have our own .popover/popover system). The rule is: native where it composes cleanly, site-class wrappers where native brings unwanted default behavior.

• Reduced motion. Respect prefers-reduced-motion; the popup/popover reveal animations should degrade to an instant open when the media query matches.

Print

The @media print stylesheet is a first-class target, not an afterthought. A printed Gwern.net essay should look like a page from a scholarly book: body serif, justified, black-on-white, no navigation chrome, no toolbar, no popups, no underlines on links; where useful, print CSS may append URLs with a[href]::after. Collapses should be expanded in print, because the reader of a printed page has no way to click them. Admonitions, epigraphs, tables, and figures should shrink gracefully to the print measure.

Rules for new print CSS:

• Do not inject color into print unless the document needs it (eg. a diagram that loses meaning without color); black & white is the default.

• Test by browser-printing; do not trust print preview in dev tools alone; some regressions show up only in the actual PDF engine.

Engineering Principles

These are the non-esthetic constraints that shape the esthetic. A design decision that violates one of them should be reworked, not shipped and optimized later.

• Progressive enhancement over framework. The frontend is hand-written vanilla JavaScript (no React, Vue, Svelte, htmx, Turbo, Alpine), coordinated by a pub/sub event bus. The HTML is Pandoc’s output, lightly rewritten by Haskell build steps. A new feature is built as: semantic HTML that works without JS → CSS that makes it beautiful → JS that adds interaction. If the third step is where the feature starts, reconsider.

• Orthogonality: Features should compose without special-casing (at least as far as the user or author is concerned).

  A class, attribute, or mechanism should work the same regardless of what else is applied alongside it: .collapse works on a section, a blockquote, a table, or a <div>; .invert/.invert-not overrides regardless of source; an epigraph can also be .poem without a special-case wrapper; transclusion combines with collapse, with reader-mode, with dark-mode…

  If a new feature requires “but not when combined with X” carve-outs, the design is wrong: either generalize X, generalize the new feature, or pick a different mechanism. The -not suffix design pattern exists precisely because negation must be orthogonal too.

• Server-side includes for global chrome. The nav, footer, and inlined-head come through Apache/nginx SSI, assembled at request time. This keeps a single source of truth for site chrome and lets us cache aggressively.

  Do not reimplement chrome in JS-templated or client-hydrated form.

• Inline the critical path. initial.css, initial-fonts-VERSIONED.css, and inlined-images-initial-GENERATED.css are inlined into the <head> at compile time; the rest of the CSS is linked and loaded with a lower priority. Keep the critical-path inline set small so the first render is fast; the full stylesheet can be large, that is fine.

• font-display: swap, always. Every @font-face declaration must carry font-display: swap. block is forbidden; it hides text for up to 3 s and is the single largest contributor to perceived slowness on font-heavy sites.

• Ship assets, not references. All fonts, icons, CSS, and JS are self-hosted. No Google Fonts, no jQuery CDN, no Font Awesome, no Cloudflare script tags (except our own CDN). 3rd-party references are tracking vectors, privacy leaks, performance black holes, and link-rot risks; pick one self-hosted solution and own it.

• Cache-busted by content hash. style-VERSIONED.css and friends carry a hash so we can set a year-long Cache-Control. When you touch a file, run the build so the hash updates; do not hand-rename.

• Single source of truth for each system.

  1. Colors → colors.css.

  2. Light/dark adjustment deltas → light-mode-adjustments.css / dark-mode-adjustments.css.

  3. Generated dark palettes → colors-dark-GENERATED.css, dark-mode-GENERATED.css.

  4. Fonts → the .ttf/.woff2 files in /static/font/ (ground truth) → font_spec.php (human index) → build_font_css.php (emits @font-face).

  5. Icons → /static/img/icon/ → icons.svg.

  Do not shadow a system in a second file because it is convenient; the shadow will drift and cause a regression.

• Lint is law. The HTML-class whitelist lives in sync.sh; a class name that is not in the whitelist is either a typo or an undocumented feature, and either way the build will complain. Add to the whitelist deliberately, in the same commit that adds the feature.

• Collection nouns only when they mean collections. Class names are singular when the class marks one thing (link-icon, margin-note, dropcap-yinit) and plural only when the class denotes a collection/system (backlinks, similars, dropcaps-*, figures). Kebab-case always (data-link-icon-type, not dataLinkIconType); -not suffixes negate (.icon-not, ., .reader-mode-not).

Anti-Patterns From The Graveyard

These are do-nots, each with a pointer to the post-mortem in the Design Graveyard. When an LLM proposes one of these, refuse it and cite the graveyard.

ffmpeg -i "$INPUT" \
  -map 0:v:0 -map '0:a:0?' \
  -map_metadata -1 -map_metadata:s -1 -map_chapters -1 \
  -c:v libx265 -preset slow -crf 26 -tag:v hvc1 \
  -pix_fmt yuv420p \
  -x265-params "colorprim=bt709:transfer=bt709:colormatrix=bt709" \
  -c:a aac -b:a 128k -ac 2 \
  -movflags +faststart \
  -f mp4 "$OUTPUT"

-vf "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709,\
    tonemap=tonemap=hable:desat=0,zscale=t=bt709:m=bt709:r=tv,format=yuv420p"

ffprobe -hide_banner -select_streams v:0 \
  -show_entries stream=codec_name,codec_tag_string,pix_fmt,color_range,color_space,color_transfer,color_primaries \
  "$INPUT"