Skip to content

Commit 1c75f81

Browse files
SongmuSongmu
authored
Merge pull request #429 from k1LoW/mddoc
doc: comprehensive documentation for supported markdown
2 parents 9380dca + 01eb723 commit 1c75f81

File tree

2 files changed

+194
-1
lines changed

2 files changed

+194
-1
lines changed

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -266,8 +266,11 @@ The system continues to operate despite an arbitrary number of messages being dr
266266

267267
![img](img/result.png)
268268

269-
### Support syntax in body
269+
### Supported Markdown syntax
270270

271+
`deck` supports CommonMark and selected GitHub Flavored Markdown extensions. For comprehensive documentation, see [Markdown Support Documentation](docs/markdown.md).
272+
273+
**Key supported features:**
271274
- Bold ( `**bold**` )
272275
- Italic ( `*italic*` `__italic__` )
273276
- Strikethrough ( `~~strikethrough~~` )

‎docs/markdown.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Markdown Support in deck
2+
3+
`deck` supports a comprehensive set of Markdown features for creating presentations in Google Slides.
4+
5+
## CommonMark Support
6+
7+
`deck` fully supports the [CommonMark specification](https://spec.commonmark.org/) with the following clarifications and limitations:
8+
9+
### Supported CommonMark Features
10+
11+
- **Headings** (H1-H6):
12+
- ATX headings: `#`, `##`, `###`, etc.
13+
- Setext headings: underlined with `===` (H1) or `---` (H2)
14+
- **Paragraphs**: Regular text blocks
15+
- **Emphasis**: `*em*` or `_em_`
16+
- **Strong emphasis**: `**strong**` or `__strong__`
17+
- **Lists**: Unordered (`-`, `*`, `+`) and ordered (`1.`, `1)`)
18+
- **Links**: `[text](url)` and reference-style links
19+
- **Images**: `![alt text](url)`
20+
- **Inline code**: `` `code` ``
21+
- **Code blocks**:
22+
- Fenced code blocks with ` ``` ` or `~~~`
23+
- Indented code blocks (4 spaces or 1 tab)
24+
- **Block quotes**: `> quoted text`
25+
- **Line breaks**: Two spaces at end of line or `<br>` tag
26+
- **Autolinks**: `<https://example.com>` and `<user@example.com>`
27+
- **Escape sequences**: Backslash escaping of special characters
28+
29+
### Character References (Not Supported)
30+
31+
`deck` does **not** support HTML character references, and there are no plans to add support:
32+
- **Numeric character references**: `&#60;`, `&#x3C;` (not supported)
33+
- **Named character references (HTML entities)**: `&lt;`, `&gt;`, `&amp;`, `&quot;`, `&nbsp;`, etc. (not supported)
34+
- **Behavior**: These references are treated as literal text and will appear as-is in the output
35+
36+
This simplification is intentional as direct Unicode characters can be used in markdown files.
37+
38+
### Raw HTML Support
39+
40+
#### Inline HTML Elements (Supported)
41+
42+
`deck` supports raw inline HTML elements for text-level semantics and edits:
43+
44+
**[Text-level semantics elements](https://html.spec.whatwg.org/multipage/text-level-semantics.html):**
45+
- `<a>`, `<abbr>`, `<b>`, `<cite>`, `<code>`, `<data>`, `<dfn>`, `<em>`, `<i>`, `<kbd>`, `<mark>`, `<q>`, `<rp>`, `<rt>`, `<ruby>`, `<s>`, `<samp>`, `<small>`, `<span>`, `<strong>`, `<sub>`, `<sup>`, `<time>`, `<u>`, `<var>`
46+
47+
**[Edits elements](https://html.spec.whatwg.org/multipage/edits.html):**
48+
- `<ins>` - inserted text
49+
- `<del>` - deleted text
50+
51+
**Not supported:**
52+
- `<wbr>`, `<bdi>`, `<bdo>` - These text-direction and line-breaking hints are not supported
53+
54+
#### Block HTML Elements (Not Supported)
55+
56+
Raw HTML block elements are **not supported** and there are no plans to support them:
57+
- Examples: `<div>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, `<aside>`, `<table>`, etc.
58+
- **Behavior**: When block HTML elements are encountered, they are treated as plain text and will appear as literal tag strings in the output (no escaping is performed)
59+
- **Rationale**: Block-level HTML elements don't map well to slide presentation structures
60+
61+
## GitHub Flavored Markdown (GFM) Extensions
62+
63+
`deck` selectively supports some [GFM (GitHub Flavored Markdown)](https://github.github.com/gfm/) extensions that are useful for presentations:
64+
65+
### Supported GFM Features
66+
67+
#### Tables
68+
```markdown
69+
| Header 1 | Header 2 |
70+
|----------|----------|
71+
| Cell 1 | Cell 2 |
72+
```
73+
- Table headers are automatically styled with bold text
74+
- Cell content supports inline formatting (bold, italic, code, links, etc.)
75+
76+
#### Strikethrough
77+
```markdown
78+
~~strikethrough text~~
79+
```
80+
- Renders with strikethrough formatting
81+
- Maps to the `<del>` HTML element internally (as specified in the [GFM specification](https://github.github.com/gfm/#strikethrough-extension-))
82+
83+
### Unsupported GFM Features
84+
85+
The following GFM extensions are **not supported** as they are not relevant for presentations:
86+
87+
- **Task lists**: Checkbox lists are not needed in presentations
88+
- **Autolinks without brackets**: It is sufficient to wrap URLs in angle brackets (`<URL>`), CommonMark autolink syntax
89+
90+
## Horizontal Rules and Page Breaks
91+
92+
Among all CommonMark horizontal rule (thematic break) syntaxes, `deck` treats them differently:
93+
94+
### Page Separators (Slide Breaks)
95+
96+
**Only** three or more consecutive hyphens from the beginning of the line create slide breaks:
97+
- `---`, `----`, `-----` etc. (no spaces, no indentation)
98+
99+
```markdown
100+
# Slide 1
101+
---
102+
# Slide 2
103+
```
104+
105+
**Exceptions that do NOT create slide breaks:**
106+
- YAML frontmatter delimiter (`---` at file start when frontmatter is present)
107+
- Files starting with `---` without frontmatter (simply ignored/removed)
108+
- Setext H2 headings (`text` underlined with `---`)
109+
- Hyphens inside code blocks
110+
111+
### Content Separators Within Slides
112+
113+
All other horizontal rule syntaxes remain as visual separators within slides:
114+
- `- - -`, `***`, `___` (with or without spaces)
115+
- Indented horizontal rules (` ---`)
116+
117+
These separate multiple body placeholders within a single slide.
118+
119+
## Line Break Handling
120+
121+
### Default Behavior (CommonMark/GFM Compliant)
122+
123+
By default, `deck` follows the CommonMark and GitHub Flavored Markdown specifications:
124+
- **Soft line breaks** (single line breaks) are rendered as **spaces**
125+
- **Hard line breaks** require either:
126+
- Two or more spaces at the end of a line
127+
- Using the HTML `<br>` tag
128+
129+
```markdown
130+
This is line one
131+
This is line two (rendered as: "This is line one This is line two")
132+
133+
This is line one
134+
This is line two (rendered with actual line break)
135+
136+
This is line one<br>
137+
This is line two (rendered with actual line break)
138+
```
139+
140+
### Alternative: `breaks: true` Setting
141+
142+
You can enable GitHub-style rendering where all line breaks are preserved:
143+
144+
```yaml
145+
---
146+
breaks: true
147+
---
148+
149+
This will
150+
render with
151+
actual line breaks
152+
```
153+
154+
When `breaks: true` is set, soft line breaks in the markdown source are preserved as line breaks in the rendered slides, similar to how GitHub renders markdown on their website.
155+
156+
## Special Considerations for Presentations
157+
158+
### Heading Hierarchy in Slides
159+
160+
Within each slide:
161+
- The **shallowest heading level** becomes the slide title
162+
- The **next heading level** (minimum + 1) becomes the subtitle
163+
- All other content goes into the body placeholders
164+
165+
Example with ATX headings:
166+
```markdown
167+
# Title (→ title placeholder)
168+
## Subtitle (→ subtitle placeholder)
169+
170+
Body content (→ body placeholder)
171+
172+
### Sub-heading (→ body placeholder)
173+
```
174+
175+
Example with Setext headings:
176+
```markdown
177+
Title
178+
=====
179+
(→ title placeholder)
180+
181+
Subtitle
182+
--------
183+
(→ subtitle placeholder)
184+
185+
Body content (→ body placeholder)
186+
```
187+
188+
### Placeholder Insertion Order
189+
190+
Content is inserted into placeholders in the order it appears in the markdown, filling placeholders from top to bottom (or left to right for same-height placeholders). If there are insufficient placeholders, remaining content will not be rendered.

0 commit comments

Comments
 (0)