# Markdown support

Wymark opens and saves ordinary markdown files, the kind GitHub shows.

## The format

| | |
| --- | --- |
| **Markdown** | [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax), with what GitHub draws on top of it: footnotes, alerts, `$` math, `mermaid` diagrams and the same [HTML tags](/docs/reference/html) |
| **Files** | `.md`, `.markdown`. `.qmd` and `.rmd` open as plain markdown. |
| **Encoding** | UTF-8 only. A file in another encoding is not opened; Wymark names it and asks for it as UTF-8. Nothing is converted. |
| **Syntax of its own** | None. Comments are HTML comments and a drawing is a PNG, so a file written here needs no conversion before it goes to GitHub, or to any other tool that reads GitHub's markdown. |
| **[Wymark comments](/docs/concepts/comments) in other apps** | Hidden on GitHub and in any other viewer that follows the markdown specification. Shown wherever the file is read as raw text: a plain text editor, a `git diff`, and a few editors whose preview shows HTML comments.                                                                                              |
| **Differences from GitHub**                            | Three things GitHub reads and Wymark does not, [listed below](#where-wymark-differs-from-github).                                                                                                                                                                                                                   |

## Constructs

Each construct has its own section on the pages below, with the syntax, what Wymark writes, and how it behaves while you edit.

| Construct | Toolbar | Shortcut | Page |
| --- | --- | --- | --- |
| Heading | Paragraph style | `⌘1` to `⌘6`, or `⌥⌘1` to `⌥⌘6` | [Text](/docs/reference/text#headings) |
| Bold, italic, strikethrough, code | Text styles | `⌘B`, `⌘I`, `⇧⌘X`, `⌘E` | [Text](/docs/reference/text#emphasis) |
| Line break | none (typed) | `⇧↩` | [Text](/docs/reference/text#line-breaks) |
| Math | Insert > Math block | `⌥⌘B` | [Text](/docs/reference/text#math) |
| Emoji | none (type `:`) | none | [Text](/docs/reference/text#emoji) |
| List | Bulleted, Numbered, Task | `⇧⌘8`, `⇧⌘7`, `⇧⌘9` | [Lists, tables and blocks](/docs/reference/lists-tables-blocks#lists) |
| Table | Insert > Table | `⌥⌘T` | [Lists, tables and blocks](/docs/reference/lists-tables-blocks#tables) |
| Quote, alert | Block quote; Insert > Alert | `⇧⌘B` | [Lists, tables and blocks](/docs/reference/lists-tables-blocks#quotes-and-alerts) |
| Code block | Insert > Code block | `⌥⌘C` | [Lists, tables and blocks](/docs/reference/lists-tables-blocks#code-blocks) |
| Divider | Insert > Divider | none | [Lists, tables and blocks](/docs/reference/lists-tables-blocks#dividers) |
| Link | Insert > Link | `⌘K` | [Links, footnotes and pictures](/docs/reference/links-footnotes-pictures#links) |
| Footnote | none (typed) | none | [Links, footnotes and pictures](/docs/reference/links-footnotes-pictures#footnotes) |
| Picture | Insert > Image | `⌃⌘I` | [Links, footnotes and pictures](/docs/reference/links-footnotes-pictures#pictures) |
| Diagram | none (a `mermaid` fence) | none | [Diagrams](/docs/reference/diagrams) |
| Drawing | Insert > Excalidraw drawing | none | [Drawings](/docs/reference/drawings) |
| HTML | none (typed in the Source view) | none | [HTML](/docs/reference/html) |

All shortcuts: [keyboard shortcuts](/docs/reference/keyboard-shortcuts). The views, the toolbar and undo: [The editor](/docs/reference/editor).

## Not supported

Wymark follows GitHub, so syntax GitHub does not read is shown as plain text.

| | Use |
| --- | --- |
| `==highlight==` | `<mark>`: see [HTML](/docs/reference/html). |
| Wiki links `[[page]]` | `[notes](./notes.md)` to link a file. |
| `\( ... \)` and `\[ ... \]` math | `$ ... $` and `$$ ... $$`: see [Math](/docs/reference/text#math). |

## Where Wymark differs from GitHub

GitHub reads these and Wymark does not. The file is not changed.

| | In Wymark | Use |
| --- | --- | --- |
| A `math` code fence, and inline `` $`x`$ `` | A code block; inline code between two `$` | `$$ ... $$` and `$ ... $`, which GitHub also reads. |
| Emoji shortcodes such as `:rocket:` | Text. | The emoji itself. Type `:` and pick one: see [Emoji](/docs/reference/text#emoji). |
| `<a name="..."></a>` anchors | Raw HTML. Not in the outline, and links to it do not jump. | A heading. Every heading is a link target: see [heading links](/docs/reference/links-footnotes-pictures#heading-links). |

## Front matter

| | |
| --- | --- |
| **YAML** between `---` lines at the top | Shown apart from the body: a collapsible card in the Formatted view, a strip above the text in the Source view. Edited as raw text. |
| **TOML** between `+++` lines | Read and edited the same way. Never written by Wymark, never converted. |
| **Versions** | Do not include front matter. A restore keeps the front matter you have now. |
| **Search and replace** | Search finds text in it. Replace does not touch it. |

Type a complete block at the top of the Source view and it becomes the card; break a delimiter and it drops back into the body.

Full syntax: [front matter on markdownlang.com](https://www.markdownlang.com/advanced/frontmatter.html).

## What Wymark adds to your file

In the Formatted view, an edit changes only the paragraph, list item or cell you edited; the rest of the file is left exactly as it was. In the Source view the file gets exactly what you type. This matters when the file is in `git` or shared with someone else.

In the part you edit, the Formatted view writes these for you:

| When you | The file gets | Example |
| --- | --- | --- |
| Press `⇧↩` in a paragraph | A backslash at the end of the line | `first line\` |
| Press `⇧↩` in a table cell | `<br>` | `one<br>two` |
| Press `↩` twice, leaving an empty paragraph | `<br>` on a line of its own | `<br>` |
| Start a list from the toolbar | `-` or `1.` as the marker | `- item` |
| Resize a picture | An `<img>` tag, because markdown has no size syntax | `<img src="cat.png" width="320">` |
| Edit a paragraph so that a line would read as a list, heading or fence | A backslash in front of it | `\* not a list` |
| Edit a paragraph where a line starts with spaces | `&#x20;` for the first of those spaces | `&#x20; indented two spaces` |
| Edit a paragraph that ended a line with two spaces | A backslash in their place | `first line\` |

Everything else stays as you wrote it, including line breaks inside a paragraph, the list marker you typed, and the spelling of `<br>`, links and URLs.