Writing

• The intended style and attitude is generally analytical, inquisitive, and precise, despite exploring complex topics, in the “classic style” of Western writing.

  • the level of formality should be inverse to the topic’s novelty: the weirder something is, the more formal. For ‘safer’ topics, one should cut loose with the humor, epigraphs, typographical stunts and experiments, etc.

  • I try to avoid hedging and qualifying, even at the risk of making overly-strong claims. It is a slippery slope.

• Because it is so reference-heavy, it risks becoming unreadable without great attention to reducing reader fatigue: the reader needs assistance navigating all the links, in the form of link-icons, deferring content to popups, collapses, standardization of vocabulary, and so on.

  These features may strike the first-time reader as clutter, but they are designed for the power-user. After enough experience, they will come to appreciate it.

• The appearance and readability of the Markdown source code is almost as important as the final product.

  If the author cannot read it, then they cannot easily improve it, and they will not enjoy writing, and risk aversion or burnout.

  And if machines cannot read it, then bugs cannot be detected, new features added, or regressions avoided; broken syntax and links, spelling errors, visual glitches, and other subtle issues will pile up over time, unnoticed.

• American spelling; I take the liberty of editing even quotes & titles in the name of consistency.

  (Since I always provide an archive of the original fulltext, I do not hesitate to modify the writing version to make it easier for the reader.)

• metric units by default. (If a quote, a metric conversion should be provided; if an idiom, then leave it alone.)

• Oxford comma

• Logical quotation

  • “&” vs “and” is used to disambiguate uses of logical operators like “and”, where the intended nesting might be unclear (eg. if one meant X AND (Y OR Z), or (X AND Y) OR Z)

• Editorial comments, whether in text or the UI/UX, are written in square brackets

• Editorial ellisions: ellipsis, but without whitespace and not in brackets (“A…B”, rather than “A … B” or “A […] B”).

  Given the heavy use of excerpts, brackets would be obtrusive, and omitting whitespace both saves space and is not ambiguous with the use of ellipsis for trailing off (“A…B” ≠ “A… B”).

• Inline author/year citations: Citations are written in the minimal possible form in the Markdown: “Surname Year[a–z]”, “Surname-1 & Surname-2 Year[a–z]”, or “Surname et al Year[a–z]”.

  They are not written in parenthetical form; instances in quoted text like annotations must be rewritten into the Gwern.net citation style.

  The citation style is important because those will be automatically detected & compiled into the subscripted ellipse form I developed for easier reading. For details on the Pandoc API conversion from the written Markdown Foo et al 2025 to the displayed “Foo et al 2025” form, see Typography.hs.

  The first use of a citation should always be to a fulltext URL, preferably annotated. (URLs are turned into a bibliography automatically, removing the need for a manual one.)

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

  • similarly, titles should be removed. 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.

  • Latinate abbreviations usually keep their period (eg. ‘eg.’, ‘ie.’, ‘cf.’, ‘etc.’)

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

  • optional: more unusual terms should be spelled out or defined in bold on their 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 capitalized to emphasize that they also do not necessarily to the laymen understanding of the word; 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 solders’ conscientiousness and predict future career success…”

    • Probability confidence terms: try to use the Kesselman words.

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

• Foreign phrases or words or sentences: italicized. Preferably translated.

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

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

• Semantic line breaks: 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 Markdown source & diffs.

• Pluralis auctoris: use “I” when describing something specific that the author did, like running an experiment (unless it was a callobration, in which case it must be “we”); use a plural 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 points, and I exclude them.

Structure

Footnotes should be <200 words; annotation commentary should be <500 words; ‘blog’ posts should be <1,500 words; essays should be <10,000 words. Past those lengths, they should probably be refactored or ‘promoted’; much below, and they may be better ‘demoted’ and moved elsewhere.

Pages should be information-dense “icebergs”: relatively short, with few blockquotes, but with many links and excerpts and related material hidden just a mouse-hover away in popups and collapses, and available through the annotated link-bibliographies, backlinks section, and similar-links reading list.

Section headers are in mixed title case. (Title capitalization is otherwise left alone—I don’t have a strong feeling on whether they should be sentence case or title case or some other capitalization.) Headers should not be more than 5 words long, to minimize line-wrapping in the Table of Contents (ToC). As the ToC is auto-generated by Pandoc, it is hard to adjust or tweak.

Sections should be at least two paragraphs long. They should not be 1 sentence long.

Sections should be structured by level of detail, roughly going left from right: section title → margin note → paragraph → footnote/sidenote → collapsed elements → excerpts or writing inside popups. This is paralleled by a hierarchy of digression: footnotes/sidenotes < collapses < appendixes

A “See Also” section should be added at the end to link relevant essays not already linked.

Unfinished or draft sections should be commented out using HTML comments: <!-- TODO -->.

HTML

• Attributes or classes are named in left-to-right general → specific style for easier Tab-completion and memory. There is always an exception, so custom classes are usually negated with a -not suffix. (Like tags or URLs, pluralization is discouraged.) They are usually written as div/span elements.¹

  Hence, there are eg. link-live, , link-icon, and icon-not classes: they pertain to a ‘link’, specify some attribute (whether the original URL can be displayed in a popup, or if it has a link-icon), and can be overridden the same way (eg. to disable a link-icon, [foo](bar){.icon-not}).

  • When there is conflict, the most specific metadata wins. If a link is on a blacklist/whitelist specified in the site-wide configuration files (the Config.* hierarchy in the Haskell source code), an attribute on a link overrides it. So if an URL is on the site-wide live-link blacklist, putting a .link-live class on a specific <a> will override the blacklist and make it a live-link.

• Page metadata:

  • “created” refers to when I had the core idea or wrote the first version, which may be when I wrote a comment on social media and not when the Gwern.net page first appeared.

  • “last-modified” refers to the last major modification of an essay, such as to add a new section or appendix.

    It does not cover minor modifications like updating broken links or adding references or paragraphs, or fixing minor errors.

    If there is a major error or obsolete material, it should be explained where it happened, possibly stored in a footnote or collapse. It may be useful to strikethrough the original text.

  • “importance” tags are 1 integer 1–10; see that page for proper usage.

  • “status”: rough ordinal of completion of an essay. Self-explanatory. (currently: “finished” • “in progress” • “draft” • “notes” • “abandoned” • “obsolete”)

  • “confidence”: how confident I am in the contents broadly, overall; must be a Kesselman word

• Poetry: currently typeset as blockquotes+<br>s. (This is not ideal and at some point we would like to support poems better, similar to interviews.)

• All essays should begin with an abstract, which is a div.abstract containing a blockquote. These are critical for popups & similar-link embedding recommendations.

  • Appendixes ought to begin with an abstract as well.

• HTML5 output: should preferably pass W3C Validator, but some of its warnings/errors must be ignored:

  • no section header for footnotes section (Pandoc-ism)

  • no alt caption on images (currently too much work to manually add to the thousands of current images, although I hope that LLMs will soon be capable of affordably adding acceptable alt-captions)

  • “Consider using the h1 element as a top-level heading only” (Pandoc-ism)

• Self-documenting: all elements should be either readable as text, or have useful metadata when interacted with (eg. tooltips on metadata fields by setting a title attribute either directly or using a span/div wrapper.)

• Divs are written in both Markdown & HTML using <div>, because the ‘native’ Pandoc syntax is ugly and dangerously finicky; spans should be written in the Pandoc [foo]{.class ...} syntax in Markdown, and as <span> in HTML

  Collapses are good to use on entire sections which are a digression and appendix-like, on large blockquotes or lists, or on transcluded annotations. They are often an alternative to a giant footnote or an appendix.

  • Collapse elements are a div.collapse/span.collapse wrapper. By default, the entire element is collapsed; to define what gets displayed while collapsed, use .abstract-collapse. To show that only when collapsed, and make it disappear when uncollapsed, use .abstract-collapse-only.

    Almost every block or inline element can be collapsed in the same way: sections, blockquotes, tables, code blocks… Due to historical reasons, Pandoc allows directly setting classes on only some elements, like sections, but not on others, like blockquotes; but the class itself remains the same, whether it’s set directly on the element or on a div-wrapper.

• Link metadata: links should encode the basic metadata of title/author/year into the title attribute of a URL (eg. [foo](/bar.pdf "'Title', Surname Year") creates an <a href="/bar.pdf" title="'Title', Surname Year">foo</a>, which with JS-disabled, will on mouse-hover show a tooltip of 'Title', Surname Year.)

  This is not because I want readers to see it (except as a fallback) but because it makes it easier to edit the Markdown source if I have the title right there to jog my memory. (It is presumably also useful to LLMs, who may not have memorized a given URL.)

• Lint/Rewrite overrides: Gwern.net relies heavily on lints and automatic rewrites to maintain consistency & correctness. This can misfire, especially when writing a document like this one which deliberately includes errors or deprecated examples. These matches can usually be disabled by inserting an invisible Unicode character like ZERO WIDTH SPACE.

• Tags: slashes on self-closing tags are never used in HTML5 (with the exception of SVG, because that is XML), particularly <img>, <br>, and <hr>.

  They were apparently a holdover from now-obsolete XHTML, and are meaningless in HTML5 (where, sans slash, they are now just “void” elements); besides triggering validation warnings and leading to inconsistent syntax where there might be (at least) 3 ways to write an element, self-closing tags kept causing mysterious sporadic problems in the overall Gwern.net stack, like a self-closed <br> would somehow turn into two of them, or horizontal-rulers would break entirely. They should never be used.

  • Pandoc definition lists are never used. I have not found any use-case for them.

• Backlinks/similar-links/link-bibliography: these are all automatically generated.

  In the case of backlinks, a backlink can be disabled at either the link level (.backlink-not) or at the page level (backlinks: False in the YAML metadata).

• Markdown source is always available for essays, using the extension .md. (eg. this HTML page, /style-manual, has its Markdown source at /style-manual.md).

Annotations

Annotations are typically the abstract of a paper, followed by excerpts. They sometimes have extensive commentary or editorial insertions (not always from myself), which are in square-brackets. These commentary may be mini-essays.

The annotation infrastructure is complicated and supports a mix of manual, semi-automatic, and automatic creation of annotations.

• Automatic: WP

• Semi-automatic: arXiv, BioRxiv/MedRxiv, some PDFs with abstracts available through Crossref, Gwern.net essays with .abstract abstracts

• Manual: everything else

Annotations do not support sections or footnotes. Sections are replaced by horizontal-rulers (<hr>) and margin-notes. Footnotes are simply written inline inside square-brackets, and can be collapsed.

Large excerpts can also be collapsed.

In some cases, collapsing parts of an annotation is not enough—like when we want to link a URL in 2 different contexts, focusing on 2 different excerpts, so we cannot simply collapse either half. In this case, we can use a hack involving anchor IDs: we simply add two new IDs to the original URL, like /doc/2025-foo.html#bar vs /doc/2025-foo.html#baz, and we write separate annotations for them, because they are now technically ‘different URLs’, even though they load the same web page.⁴ In the special case of PDFs, when this happens, we can usually exploit the built-in page-number anchors to get more useful IDs by specifying the most relevant #page=N for the two different use-cases.

“Keywords” are removed from papers that provide them. While they may have been highly useful for librarians indexing documents in the pre-computer era, they are almost never useful now due to extreme inconsistency in the controlled-vocabulary across all authors/publishers—and even the small benefit they still provide to skimming is obsoleted by the fact that all of the keywords will usually be hyperlinked or bolded & jump out that way. (They can be left hidden in a comment to provide hints to an embedder, but otherwise are a waste of space.)

Bulletpoint list summaries are used by a few academic publishers or authors to summarize the summary. Laid out normally, they take up a great deal of vertical space while being redundant with a properly-linebreaked or topic-split abstract. We keep them, but we condense them to be a single inline list with BULLETs, and separate with a horizontal ruler.

Similarly, some publishers provide a ‘layman’ or ‘plain’ or ‘public’ abstract along with the scientific abstract. Those should be presented first, and separated with a horizonal ruler.

Code

• Comments should focus on the “why” and especially the “why not”, and not on the “how”.

• All code blocks should specify a language for syntax highlighting, using Pandoc syntax highlighting. (Even when something in a code block is pseudo-code or not strictly any language, the skylighting suite usually has something which will give useful results.)

  • Inline code syntax highlighting is optional.

Generative Media

Generative models like LLMs or image-generators are good servants, but as of mid-2025, poor masters.

My policy for generative media is that generative model outputs must be improved.

Outputs of models should be clearly identified as such in the filename/caption, or body; they should be critiqued as right or wrong, and errors noted.

Random uncurated outputs should never be used, except in an explicit context of ‘random uncurated outputs’.

If text or images are being used, perhaps for illustration, they should be high quality & carefully considered. If they could have been generated in just a few minutes of prompting, and they have no clear connection to the essay or any depth, they should not be used at all. Ideally, they will look as good in 10 years as they do today, and they will not look blatantly dated or buggy. (The widespread use of cheap DALL·E 3 images on Substack, often barely a step up from Bing-style “Shrimp Jesus” images, are an excellent example of what not to do.)

In particular, they should avoid the artifacts and stereotypical mode-collapsed styles of the used model. There should be no visible artifacts like malformed hands or weird backgrounds that make no geometric sense. Style-wise, Midjourney samples should never feature “Instagram women”; GPT-4o images should avoid sepia/yellow color palettes; LLM output should avoid notorious tells like “delve” or the GPT-4o “em-dash twist ending”. Images should have a strong esthetic and tend towards monochromatic; if there is no specific color theme, it should be grayscale. (A HDR-esque ‘every color at once’ is one of the more reliable tells of a RLHF process dumbing a generative model down to the lowest common denominator.) You can fight this laziness with personalization, heavy use of high-temperature-like settings, getting illustration ideas from the most creative models like GPT-4.5, and stubborn insistence on fixing errors.