Ken's syntax derives from Github-Flavored Markdown (which in turn derives from CommonMark). We do not repeat the content of those specs here; we just describe the differences.
To improve consistency and readability, and to make parsing easier, ken removes some optional, uncommon markdown constructs. No expressive power is lost.
| removed construct | comment |
|---|---|
| some thematic break variants | Ken recognizes three or more underscore characters (___) as a thematic break and converts them to <hr>. Ken treats exactly three hyphens (---) as a YAML c-directives-end symbol, allowing YAML front matter for document metadata. Ken does not consider runs of three or more * characters as special. |
| Setext headings | Use ATX headings instead. Eliminates examples 50-76 from the GFM spec. |
Trailing # on ATX headings |
Unnecessary. Eliminates examples 41-46 from the GFM spec. |
| leading tabs | Indents created with mixed tabs and spaces creates surprises. Indent with 4 spaces instead. Leading tabs are an error. |
| extra leading spaces | Many markdown implementations ignore sequences of 1 to 3 extra leading spaces at the beginning of a line, so a 2-space indent has the same meaning as no indent, and a 7-space indent has the same meaning as a single 4-space indent. You can see a requirement to support this behavior in GFM's 4.1 Thematic Breaks, for example. Ken disallows this behavior. Indent as much as you need, but don't put extra leading whitespace on a line. |
Regular markdown often provides more than one way to do the same thing. Ken provides only one way. Alternatives are repurposed to increase expressiveness. Some new syntax is added.
Regular markdown treats all the bullet characters as synonyms, and always renders them with a filled-in disc • (CSS list-style-type: disc). In ken, only the * is for bullets, and it can be styled. To style, add : plus a value of the CSS list-style-type. The style applies to all subsequent bullets in the same list. So, for bullets that are open circles ○, the first item in a list should be *:circle First item; for squares ■, the first item in a list should be *:square First item; and so forth.
You can also use a single arbitrary unicode character as a bullet by substituting it for the token after :. For example, to have list items that are checkmarks, use *:✓. (Ken is always UTF-8. What you put here is one logical unicode codepoint, even if it takes more than one byte to represent.)
Regular markdown treats + as a bullet prefix. In ken, this followed by an indented block beneath it maps to a collapsible HTML 5 <details><summary>...</summary><section>...</section></details> structure. The effect in most browsers is similar to a treeview or collapsible outline.
+ My Section Title
Section content
▼
<details
<summary>My Section Title</summary>
<section>
Section content
</section>
</details>TODO: how to say whether the section is open or closed by default. TODO: should summary be styled like a header? Maybe only if followed by a header?
For safety and simplicity reasons, ken docs are assumed to intend embeddable mode only. The transformation of individual files can always be forced into standalone mode with the --standalone-mode switch. Alternatively, the --natural-mode switch will render all files in their natural mode.
A file can declare or inherit a standalone prefix and/or standalone suffix property; the direct declaration of such a prefix or suffix changes the natural mode for the content to standalone. During standalone mode transformation, the content of standalone prefix is prepended to the main output as if it were a pure HTML fragment that contained all structure up to and including <body>; the content of standalone suffix is appended as if it were a pure HTML fragment that contained at least </body></html>.
The sanitization of embeddable mode allows the same tags, HTML attributes, and CSS attributes as HTMLSanitizer's default posture. Note that this is substantially richer than the set allowed in Github Markdown.
Any HTML constructs beyond this require standalone mode.
See hypertext.
ken supports includes as a convenience.
Mustache templates are supported. A number of predefined metadata variables are defined:
{{doc.*}}— Document attributes:size,lastmod,author,commit-hash,version,relative-path...{{time.*}}— Timestamps in various formats:yyyy-mm-ddThh:nn:ss.xZand similar.{{space.*}}— Information about the codebase that contains the doc:doc-count,upstream,origin.