Style Guide

---
# This is YAML frontmatter, *not* a setex heading
title: Style Guide
banner: text-kel
---

While this site is primarily Markdown-based, and strives to be capable
of rendering Markdown text faithfully to the CSS on /r/teslore[^1], it
extends the Markdown processor to allow a much richer set of controls
than reddit, or even standard Markdown, can express.

We edit the source texts scraped from reddit in order to give them a
better semantic structure, embed linked media directly in the document,
and take full advantage of our technical capabilities.

## How Our Markdown Works

The Markdown text used to create this page is pasted at the bottom, so
you can compare the text that I wrote to the browser page that you see.

In addition to the CommonMark standard, we support:

- footnotes: these use the reference-link syntax, but begin the link ID
  with a caret: place `[^num]` in your document to create a
  superscripted footnote link, and `[^num]: text` at the *end* of the
  document to fill in its text.

  The text can span multiple lines, and is not indented like list items
  are.[^2]

- superscripts: like reddit, we have superscripts; unlike reddit, we
  require a leading and trailing caret: e^𝑖π^ = -1.

- subscripts: these are delimited by single tildes (`~`): C~6~H~12~O~6~
  is a simple sugar.

- TES fonts: Using custom classes (described next), you can render some
  text in fonts taken from the games. `.handwriting` uses the *Skyrim*
  journal font; `.dovah`, `.dwemer`, `.falmer`, and `.daedric` do
  exactly what they say, and `.ehlnofex` uses the font shown on the Eye
  of Magnus. You can also use an IAL to apply the `lang="x-NAME"`
  attribute.

- HTML attributes: the “inline attribute list” allows you to write HTML
  attributes and attach them to the HTML tag that your Markdown will
  produce.
  *This text is colored by an IAL.*{:style="color: forestgreen;"}

- HTML tag replacement: the special attribute `{:tag="new_tag"}` causes
  the Markdown engine to change the generated tag to use the provided
  tag, preserving the rest of its attributes and children. This means
  that you can turn `> blockquotes` or `*italics*` into arbitrary block-
  or inline- HTML elements.

  Restrictions: the Markdown engine *does not parse* inside code spans.
  You can still rewrite their tag, but their contents are shown
  verbatim.

  Additionally, Markdown blocks that produce two-layer HTML nodes
  (triple-backticks produces `<pre><code>`; `- list` produces
  `<ul><li>`, and `1. list` produces `<ol><li>`) discard their IALs, as
  the engine cannot determine whether the attributes should be attached
  to the outer or inner layer.

- YAML frontmatter: hosted apocrypha require some metadata alongside the
  actual text. This is how we manage collecting posts into a series
  (`series:` and `part:`), provide a `title:` and `subtitle:`, link to
  the original `reddit:` post ID, name the `author:` who wrote it, and
  show the `date:` at which it was posted. You can also specify a
  `banner:` image from the following:

  - `c0da-1` through `c0da-4`
  - `dragons` or `dragons-sepia`
  - `elder-scroll`
  - `magnus`
  - `map-cyrod`, `map-skyrim`, `map-stylized`, or `map-wilderness`
  - `numinatus`
  - `oblivion`
  - `seas`
  - `text-daedric`, `text-kel`, or `text-oghma`
  - `tools` or `tools-active`
  - `wilds`, `wilds-morrowind`, or `wilds-morrowind-2`

## What Your Markdown Should Be

Now that reddit has deprecated custom CSS, *chances are* your audience
isn’t looking at your post on <https://old.reddit.com/r/teslore>, so
they aren’t seeing the custom CSS. You should write your Markdown
normally. This means:

- use `## actual headings` for sectioning, not bolds or blockquotes to
  simulate headings.
- don’t use `# h1` *at all*. The template injects the document `title:`
  as the only `<h1>` element, and the optional `subtitle:` right below
  it as an `<h2>`. The Markdown engine automatically downgrades `# h1`
  elements to `## h2`.
- *don’t* use headings to manage your text size. We have CSS classes for
  that.
- use `> blockquotes` liberally, and name the source *inside* the blockquote
  with an IAL:

  > This is a blockquote. It even has a citation attached!
  >
  > This is the citation.
  > {:tag="cite"}
- prefer using *italics* for your inline IAL replacements, rather than `code`,
  since engines that don’t process IALs will still render this as visually
  distinct but not obnoxiously strange
- we don’t acknowledge, and in fact actively remove, trailing whitespace on
  lines of text. this means that trailing spaces can’t be used to create
  `<br />` elements. If you need those, the only way to create an empty inline
  element is, unfortunately, an empty link: `[](){:tag="br"}`.
- wrap your lines at 80 columns

[^1]: conveniently, /u/myrrlyn is the author of both /r/teslore’s CSS
and this website, so compatibility is only a question of motivation, not
ability.
[^2]: yes, it’s a little confusing, but that’s life.