Table of Contents

Coursage Markdown

Documents on Coursage sites use Markdown — a formatting language with no single precise specification and many flavors. Coursage uses a variant called Kramdown (quick reference, full syntax) with the Kramdown GFM parser. Most Markdown syntax that works on GitHub will also work here, along with some Kramdown extensions such as inline attributes.

On top of this already-confusing syntactic dogpile, this site adds custom styling and a variety of custom tags. Some of those carry semantics that affect site behavior.

Docs on this site mostly place each paragraph on a single long line, rather than placing
internal lines breaks
in the paragraph like this
to keep lines short in
the text editor.

Docs on this site mostly place each paragraph on a single long line, rather than placing internal lines breaks in the paragraph like this to keep lines short in the text editor.

The rationale is that hard-wrapping text at 80 or 100 produces very noisy Git diffs when a paragraph is rewrapped — and most modern Git clients do a decent job of highlighting when only a small portion of a long line has changed in a diff. Programmer’s text editors generally have a “wrap lines” feature with at least some awareness of indentation, which is the best way of editing these md files. This approach does mean that you’ll need to turn on that feature in your editor. Sorry!

  Some docs use “typographic quotes” and some use "ASCII quotes." They all come out the same in the output HTML. Isn't / isn’t it grand? To disable this smart quotes feature, mark ASCII quotes as code using backticks: `‌' "`‌.

Some docs use “typographic quotes” and some use “ASCII quotes.” They all come out the same in the output HTML. Isn’t / isn’t it grand? To disable this smart quotes feature, mark ASCII quotes as code using backticks: ' ".

  Some docs use em dash characters — like this. You can also spell out em dashes using the Markdown syntax of three hyphens --- like this.

Some docs use em dash characters — like this. You can also spell out em dashes using the Markdown syntax of three hyphens — like this.

Note that three hyphens are an em dash (for emphasizing boundaries between clauses), while two hyphens are an en dash (for delimiting ranges). (No, I don’t like this either, but this is the Way of Markdown.)

- ❌ The em dash offsets clauses -- if you choose it.
- ✅ The em dash offsets clauses --- if you choose it.
- ✅ The em dash offsets clauses — if you choose it.
  • ❌ The em dash offsets clauses – if you choose it.
  • ✅ The em dash offsets clauses — if you choose it.
  • ✅ The em dash offsets clauses — if you choose it.
- ❌ You’ll typically use an en dash only 0-2 times in a doc.
- ✅ You’ll typically use an en dash only 0--2 times in a doc.
- ✅ You’ll typically use an en dash only 0–2 times in a doc.
  • ❌ You’ll typically use an en dash only 0-2 times in a doc.
  • ✅ You’ll typically use an en dash only 0–2 times in a doc.
  • ✅ You’ll typically use an en dash only 0–2 times in a doc.

(Educational video about dashes)

Since some .md files do contain non-ASCII characters, make sure you edit them all as UTF-8.