Skip to main content

Voice Rules

Writing constraints every page is held to. Edit per wiki to match the operator's house style.

Pages here are written by Gary Sheng, in the first person where the experience is his, and in plain language for anyone who just found out they have aphantasia, or loves someone who does.

Page anatomy (non-negotiable)​

  • Frontmatter with title, slug, description, sidebar_position (where applicable).
  • H1 matches the title.
  • Italic one-line definition directly under the H1.
  • --- divider before the body.
  • 3-5 named H2 sections in the body.
  • "Further Reading" section at the bottom with cross-links.

Voice​

  • Direct, economical. Every word earns its place.
  • Concrete over abstract. Specifics over categories.
  • No em dashes. Use periods, commas, or colons instead.
  • No motivational poster language. No clichés.
  • Warm and honest. Name the costs as well as the gifts.
  • Every factual claim about research carries a link to its source.
  • Never frame aphantasia as a disease or a deficiency to be fixed.
  • Define every term in the Glossary. Cross-link, do not redefine.

Admonitions​

Docusaurus 3 runs MDX 3, and a directive title goes in brackets:

:::note[About the sources]
Body text.
:::

The old space-separated form (:::note About the sources) renders as literal text on the page, :::note and all. It does not error, and pnpm build still exits 0, so nothing catches it. The only detector is looking at the page or grepping for the pattern:

grep -rnE '^:::(note|tip|info|warning|danger|caution)[[:space:]]+[^[[:space:]]' docs/

A bare :::note with no title is fine and needs no brackets.

Cross-linking​

  • Use Docusaurus-style absolute paths: /my-story/moving-on, not relative.
  • Every page should link to at least two other pages in the Further Reading section.
  • Concepts link to each other. The lexicon is a graph.