Writing mechanics

The smallest characters carry the most convention. This page covers two families of them: the dashes between words, and the emoji between sentences.

Dashes#

Three horizontal marks, three jobs. The keyboard offers only the shortest one, so the other two get skipped or misused.

Hyphen (-)#

The key beside 0. It joins:

• Compound modifiers before a noun: well-known, up-to-date, first-quarter results
• Prefixes where clarity needs it: re-cover a chair, not recover a file
• Words broken across a line, which is the typesetter’s job, not yours

En dash (–)#

The width of an “n”. It marks spans and pairings:

• Ranges, read as “to”: pages 3–5, 2020–2026, Monday–Friday. Do not pair it with “from” or “between”: write from 2020 to 2026, not from 2020–2026.
• A relation between two peers: the Montréal–Toronto route, a client–server split.

Type it: ⌥- on macOS, Alt+0150 on Windows, – in HTML.

Em dash (—)#

The width of an “m”, and the only one that works at sentence level:

• A break stronger than a comma and lighter than parentheses
• A matched pair that sets off an aside: The plan — debated for months — finally shipped.

Keep it to one pair per sentence. US style closes it up, like—this; many house styles and most of the web space it out, like — this. Pick one and hold it.

Type it: ⇧⌥- on macOS, Alt+0151 on Windows, — in HTML.

Picking one#

• Two words, one idea: hyphen
• One value to another: en dash
• A break inside a sentence: em dash

On this site#

This site enables Goldmark’s typographer extension, so Markdown does some of the work: -- renders as an en dash, --- as an em dash, and straight quotes and apostrophes turn curly. Typing the real – and — characters works too, and stays unambiguous in files that other tools also read.

Emoji#

Emoji shortcodes such as :tent: are application conventions, not a standard, so pages here do not depend on them; the {{< emoji >}} shortcode reads the curated emoji table in data/series/ref/emojis.yml instead. For GitHub specifically, use GitHub’s official REST API endpoint for emojis rather than old community-maintained shortcode gists.

Maintaining that table means deciding which source to trust for each field. Emoji metadata is deceptively complex to maintain: names, codepoints, shortcodes, and text fallbacks often pull from different sources with varying levels of authority 🤷‍♂️. To keep the website reliable, authoritative specifications are strictly separated from platform conventions and curated fallback text.

Source authority#

Shortcode presets are conventions, not standards#

Emoji shortcodes (e.g., :smile:) are not governed by Unicode. They are platform-specific UI conventions:

• Emojibase mapping: Emojibase maps discord shortcodes as an alias for JoyPixels and slack shortcodes as an alias for the iamcal preset

Neither Discord nor Slack publishes an official, complete shortcode API dataset. These preset labels are treated as practical compatibility hints, not immutable specification guarantees.

Emoticons and kaomoji require hand-curation#

Text conventions like emoticons (:-/) and kaomoji (¯\_(ツ)_/¯) have no central governing body:

• ASCIImoji: easy to parse, but offers limited coverage
• Wikipedia emoticon list: broad historical context, but lacks the structured consistency needed for automated data pipelines
• Takeaway: maintenance requires a curated local field checked against community references

Apple display labels#

While Apple Color Emoji is the predominant platform rendering, Apple — unlike GitHub — does not publish an official public shortcode or naming API. Platform-specific Apple labels are treated as editorial context, not primary database columns.