# Markdown Publishing ## Write in plain text, publish anywhere ### Macstock 2026 Note: - Welcome everyone — I'm Brett, and this is Markdown Publishing - Roughly 45 minutes of presentation, then 45 minutes to play with Marked and other tools on your own machines - I'll pause the slideshow for live demos — Markdown Dingus, export, the good stuff - If you're following along on the public URL, links and copy buttons work as we go ^^^ ## Follow along on your device Slides sync live — tap links, copy code as we go. QR code [dub.sh/ms2026](https://dub.sh/ms2026) Note: - Pull out your phone or laptop — scan the QR code or type dub.sh/ms2026 - Your view stays in sync with mine as I advance slides - I'm the master on localhost — you don't need any special setup, just the URL - Tap links, copy code from the slides — it's all interactive on your end ^^^ ## Bookmark slides you want to revisit ### Lower-left controls - **Bookmark** — save the current slide on this device - **Menu** — open your bookmark list; tap a title to jump back - Tap bookmark again on the same slide to remove it Bookmarks stay in your browser — use them to get back to code samples, pages of links, and anything you want to revisit. The slideshow will remain hosted at [dub.sh/ms2026](https://dub.sh/ms2026) after the session. Note: - The slideshow will remain available after the talk and indefinitely on my server, so you can refer back to it at any time, today or in the future. - Look at the lower-left corner on your phone or laptop — two icons - Bookmark icon saves this slide locally — no account, stored in your browser - Hamburger opens the list — tap a title to jump back to that slide - Tap bookmark again to remove; × in the list removes without jumping - When I advance slides, your view follows me — bookmarks are for when you want to revisit something on your own after the talk ^^^ ## Copy code blocks Every code block has a "Copy" button, click it to copy the whole code block as plain text. --- # What makes me cut out to present at Macstock? --- ## Why Markdown? - **Plain text** — readable forever, no proprietary lock-in - **Portable** — works in any editor on any platform - **Separation of concerns** — content vs. presentation - **One source** → web, PDF, EPUB, Word, print Note: - So here's the thesis for the whole session: write your content once, publish it many ways - Plain text is the most durable format we have — no vendor can take it away. No lock-in to one app (ahem, Evernote) - You write words; templates and processors handle the layout — that's called separation of concerns - The same Markdown file can become a blog post, a PDF, an EPUB, a Word doc — we'll walk through how --- # History of Markdown ## John Gruber's original vision - Created by **John Gruber** — announced **March 15, 2004** on [Daring Fireball](https://daringfireball.net/2004/03/introducing_markdown) - **Aaron Swartz** helped refine the syntax and wrote `html2text` - Goal: write for the web in **plain text that reads well before you render it** - Borrowed from **email**, **Usenet**, and **BBCode** — but simpler and more universal Note: - March 15, 2004 — Gruber posts "Introducing Markdown" on Daring Fireball - Aaron Swartz (RIP, that's a tragic story), he helped refine the syntax and built html2text - The goal was simple: write for the web without hand-coding HTML - No toolbar, no WYSIWYG — just text that reads like email even before you render it - He borrowed ideas from email conventions, Usenet, BBCode — but made it simpler and universal ^^^ ## HTML vs Markdown Same content — notice which one you can actually read: ```html

Read Daring Fireball for the original announcement.

Markdown is bold and italic without tags everywhere.

``` **And now, in Markdown** ```markdown Read [Daring Fireball](https://daringfireball.net) for the original announcement. Markdown is **bold** and *italic* without tags everywhere. ``` Note: - Side-by-side moment — same paragraph, two formats - HTML is full of angle brackets, closing tags, href attributes — fine for browsers, painful to write - Markdown: the link, bold, and italic are visible in the plain text itself - This is Gruber's whole point — write for humans first, let the processor generate the HTML - which would you rather maintain for a blog post or book? ^^^ ## Markdown today - Everywhere: **GitHub**, Slack, Discord, Reddit, Notion, Obsidian… - The default for READMEs, docs, wikis, and comments - **AI era** — ChatGPT, Claude, and Cursor output Markdown by default - Plain text won: notes → blog → PDF → LLM context, one format Note: - Fast-forward twenty years — Markdown is everywhere you look - GitHub READMEs, Slack messages, Discord, Reddit, Notion, Obsidian — all of it - Ask ChatGPT or Claude for formatted output and you get Markdown back - Structured enough for machines, readable enough for humans — that's why AI speaks it fluently - One format carries you from daily notes to blog posts to PDF to LLM context ^^^ ## Markdown timeline 
timeline
    title Markdown History
    2004 : Gruber & Swartz
         : Markdown announced
    2014 : CommonMark spec
    2017 : GFM on GitHub
    2020s : Obsidian & PKM boom
    2023+ : AI default output
Note: - Quick visual — twenty years in one timeline - 2004: Gruber and Swartz, the original announcement - 2014: CommonMark tries to nail down a spec — we'll come back to that - 2017: GitHub Flavored Markdown on every repo - 2020s: Obsidian and the personal-knowledge-management explosion - 2023 onward: AI tools default to Markdown output — full circle --- # Markdown-First Apps ## You're probably already using Markdown Note: - New section — and I bet a lot of you are already Markdown users without calling it that - We're going to look at Mac apps where Markdown isn't an export format buried in a menu — it's the native format ^^^ Many popular Mac apps treat Markdown as their **native format** — not an export option buried in a menu. Your notes, journals, and drafts are plain text underneath. Note: - Bear, Obsidian, Ulysses, Drafts — they all store plain text with lightweight markup - What you see on screen is rendered; what's on disk is Markdown or close to it - Show of hands — who uses any of these? - If you raised your hand, you're already in the Markdown ecosystem ^^^ ## Notes & daily capture - **Bear** — tagged notes, beautiful typography, `#tags` - **NotePlan** — calendar-linked notes and tasks - **Obsidian** — linked notes in a local vault, `[[wiki links]]` - **Drafts** — quick capture with Markdown actions - **nvALT / nvUltra** — quick note-taking, Markdown-based Note: - These are great on-ramps — you write naturally and syntax stays out of the way - Bear: tags and beautiful typography — `#tags` everywhere - NotePlan: your notes live on your calendar - Obsidian: wiki links between notes — `[[like this]]` - Drafts: capture first, process later with actions - nvALT and nvUltra: keyboard-driven, search-first — my daily driver for years ^^^ ## Linked notes (Obsidian-style) 
graph LR
    DN[["Daily Note"]] --> PX[["Project X"]]
    PX --> MN[["Meeting Notes"]]
    MN --> DN
    PX --> RF[["Reference"]]
Note: - This is the Obsidian mental model — notes that link to other notes - Daily note connects to a project, project connects to meeting notes and references - The graph view is eye candy — the habit of linking ideas is what actually matters - You don't necessarily need Obsidian for this — it's a way of thinking about your notes. Marked can recognize and navigate this type of wiki link as well. ^^^ ## Writing & long-form - **Ulysses** — library of sheets, writing goals, publishing export - **iA Writer** — distraction-free, Focus Mode, syntax highlighting - **Typora** — seamless WYSIWYG Markdown editing - **Lettera** — rich-text-like editing with live in-place rendering ([lettera.md](https://lettera.md/)) - **One Markdown** — clean, minimal native editor Note: - Markdown isn't just for developers or quick notes — it's for real writing - Ulysses offers a library of sheets, goals, export to publish - iA Writer provides distraction-free writing, with a Focus Mode that dims everything but the current sentence - Typora: what-you-see-is-what-you-get — formatting without syntax visible - Lettera: new from the Bear team, currently in public beta — feels like rich text, renders Markdown live in place - Pick the app that matches how you think — linked notes vs. linear docs vs. quick capture --- # Markdown Basics ## Just write — it's already Markdown Type plain text. Separate paragraphs with **blank lines**. That's valid Markdown — no markup required. ```markdown First paragraph. Just sentences. Second paragraph. Another thought. Third paragraph. You're writing Markdown. ``` Note: - Before we talk about hash marks and asterisks — you may already be writing Markdown - Plain text with blank lines between paragraphs is valid Markdown everywhere - No syntax required for the basics — processors turn this into HTML paragraphs automatically - This was Gruber's whole point: readable as plain text first, markup only when you need it ^^^ ## Whitespace Most processors **ignore single line breaks** — they collapse into one paragraph unless you add a **blank line**. - **Blank line** → new paragraph - **Line break only** → same paragraph (or a soft break in some processors) - **Two spaces at end of line** → forced line break inside a paragraph Note: - This trips up almost everyone at first — one Return does not make a new paragraph - Blank line is the rule; line break only keeps you in the same paragraph ^^^ Inside a **list**, nesting needs a blank line plus **4-space or tab indent** (extra indent for code). ```markdown [1-4|6-7|9-11|13] First paragraph line one First paragraph line two Second paragraph — blank line above Line with a forced break at the end Next line stays in the same paragraph 1. Top-level item Nested paragraph (blank line + 4-space indent) - Nested list item (blank line + indent) ``` **When in doubt, add a blank line** — before and after headings, lists, block quotes, and code blocks. Note: - Two spaces at end of line forces a break inside a paragraph - Lists: blank line plus indent for nested paragraphs or sub-lists (with a list marker); add an extra indent for code/verbatim text - Never be afraid of whitespace — generous blank lines prevent parser surprises ^^^ ## Headlines, lists, and more ```markdown [1|3|5-6|8|10|12|14|16] # This is a header 1 ## This is a header 2 This is a paragraph with **bold** and *italic* text. This is also __bold__ and _italic_, personal preference. - This is a list item, lists can start with `+`, `-`, or `*` 1. This is a numbered list item (always a 1 and a .) > A blockquote for callouts [A link](https://example.com) `inline code` ``` Note: - Now the markup — I'll step through line by line, watch the highlights - Headers: one through six hashes - Bold and italic can use asterisks or underscores, your preference, one for italics, two for bold - A list can start with a dash, a plus symbol, or an asterisk. A lot of people (and apps) use different markers at different levels, but they all render the same as bullet points - A numeric list starts with a 1 and a . The rest of the numbers in the list don't have to be in order, as long as the list starts with 1 dot, the rest of the list will be numbered in order. - Note that if a list at the same indentation level starts with one or the other, the rest of the list will adopt the first marker type at that indentation level. - Block quotes just start with a greater than symbol on each line. The same whitespace rules apply, so to add a blank line within the block quote, add a line with just a greater than symbol and nothing else. - Inline code is surrounded with backticks, the key under your escape key. - As you can see, even with markup added, it still reads like email ^^^ ## More on links **Inline** — URL right in the sentence: ```markdown Read [Daring Fireball](https://daringfireball.net) for the original announcement. ``` **Reference style** — label in text, URL at the bottom: ```markdown Read [Daring Fireball][df] for the original announcement. [df]: https://daringfireball.net ``` Note: - Two ways to do links — inline and reference style - Inline: URL right in the sentence — fine for one-offs - Reference: label in the text, URLs collected at the bottom (or after each paragraph) — much cleaner docs with a lot of links - You can mix both in the same document - Reference style is closest to Gruber's vision — prose stays readable, URLs stay out of the way ^^^ ## More basics ```markdown [1|3|5-7] ![Alt text](image.png) Indented code block * * * Horizontal rule (three dashes or asterisks on their own line) ``` Note: - Images: always include alt text — accessibility matters. Some processors will turn alt text into captions, so know what to expect with experimentation. - Indented blocks are verbatim blocks — spacing and line breaks preserved - Good for code, but also poetry or anything where line breaks matter - Four-space indent works; fenced blocks on the next slide are the modern way - Horizontal rule: three dashes on their own line — but careful, `---` at the top of a file is YAML front matter in many tools ^^^ ## Fenced code blocks ````markdown ```python def hello(): print("Hello, Macstock!") ``` ```` Note: - Triple backticks — optional language tag for syntax highlighting - This is what you'll see in GitHub READMEs and docs everywhere - Most processors highlight Python, JavaScript, bash, and dozens more --- # How did the hipster burn his mouth on his coffee? # He sipped it before it was cool. --- # Advanced Markdown ## A little past the basics Not every processor supports everything here — check your flavor before you rely on it. Note: - I'm going to whiz through this section, so bookmark this slide if you want to come back to this section easily. - Quick tour of Markdown beyond headers and lists - Some of this is GFM, some MultiMarkdown, some Kramdown or Apex only — I'll call out the picky parts - Don't memorize it all — know what's possible when you need it ^^^ ## Nested blockquotes ```markdown [1|3|2] > Level one — the main quote > > > Level two — nested inside ``` Add a `>` for each level. Blank lines still matter inside quotes. Note: - Prefix each line with `>` — add another `>` for nesting - Great for quoting someone who quoted someone else - Supported in most processors; spacing rules still apply ^^^ ## Callouts - **Apex** supports many callout types when publishing — **no other processor** in a typical pipeline does. - **Obsidian**, **Bear**, and **Xcode** render callouts in-app, even if your export path ignores them. - **Marked 3** handles all callout syntaxes ```markdown > [!note] Title > Body text for a note callout. > [!warning]- Title > Collapsed by default — click to expand in Obsidian and Bear. ``` The `-` after the type collapses the callout. Types vary by app (`note`, `warning`, `tip`, `important`, …). Note: - Obsidian-style callouts — blockquote syntax with a tag in brackets - Apex is the outlier for publishing: note, warning, tip, and more in unified mode - Pandoc, GFM, Kramdown, MultiMarkdown — they won't render these on export unless you add custom CSS or a preprocessor - Bear, Obsidian, and Xcode understand them natively — great for notes, risky for cross-platform publish - The minus sign after the type means collapsed by default in Obsidian and Bear - If you're writing for a static site, check your processor before relying on callouts ^^^ ## Nested lists Use **4-space indentation** per level — works almost everywhere. ```markdown 1. First item 1. Nested numbered 2. Another nested - Bullet - Nested bullet - Third level ``` Note: - Four spaces per indent level — tabs often work too, and I actually like them better - A lot of GitHub users develop what I consider to be a bad habit of using 2 spaces. This works in about 60% of markdown flavors, but 4 spaces/1 tab works in 100% - We covered list nesting and whitespace on the basics slide — this is the everyday pattern ^^^ ## Definition lists **MultiMarkdown**, **Pandoc**, and **Apex** — not plain CommonMark. ```markdown Markdown : A plain-text formatting syntax Marked : A live preview app for Markdown on Mac ``` Term on one line, `: definition` on the next. Note: - Glossary and dictionary style — term, colon, definition - This was invented in MultiMarkdown. It won't render in GitHub-flavored Markdown or bare CommonMark - Handy for docs and reference sections ^^^ ## Markdown tables Header row, alignment row, data rows — **GFM** and most modern flavors. ```markdown | Flavor | Best for | |:----------|-----------:| | GFM | GitHub | | Kramdown | Jekyll | ``` `:---` left · `:---:` center · `---:` right Note: - Pipes and dashes — header, alignment row with colons, then data - Alignment row controls column text alignment in the rendered output - Keep cell content simple — we'll talk limits on the next slide ^^^ ## What tables can't do - **No line breaks** inside a cell (in standard Markdown tables) - No merged cells, nested tables, or block elements in cells - Wide tables can be painful to edit by hand For complex layout, use HTML Note: - One line per cell — if you need a paragraph inside a cell, you're in HTML territory - Colspan and rowspan exist in Apex but not in basic GFM — don't assume - This is why visual table tools exist — typing pipes gets old fast ^^^ ## TableFlip **[TableFlip](https://tableflipapp.com/)** — $9.99 Visual table editor for Mac. Edit in a spreadsheet-like UI; save as Markdown, CSV, or JSON. **Flipping** keeps a `.md` file and the table in sync. Note: - tableflipapp.com — Christian Tietze's app, built for Markdown tables - Open a Markdown file, edit the table visually, save — the file updates - Thirty-day trial; pairs nicely with Marked for preview - If you maintain any tables in your writing, this pays for itself quickly ^^^ ## MultiMarkdown Composer tables **[MultiMarkdown Composer](https://multimarkdown.com/composer/)** includes strong **table automation** — tab between cells, auto-growing rows, alignment without counting pipes. Another good option if you're already in the MMD ecosystem. Note: - MMC is built for MultiMarkdown — tables are a first-class feature - Tab around the grid, rows grow as you type — less hand-formatting than raw pipes - Between TableFlip and MMC you have visual options; raw Markdown still works everywhere ^^^ ## Markdown Service Tools macOS **Services** (right-click in any text field) for Markdown chores. **[Markdown Service Tools](https://brettterpstra.com/projects/markdown-service-tools/)** — convert indented text to lists, flip inline/reference link styles, clean smart punctuation, clean up tables, wrap selections, and more. Note: - Free download from brettterpstra.com — installs as system Services prefixed with "md" - Turn tab-indented lines into a bullet list, flip a link from inline to reference style - Works in BBEdit, TextEdit, Mail — anywhere you can select text - Assign keyboard shortcuts in System Settings for the ones you use most ^^^ ## md-fixup Command-line linter and formatter — cleans up Markdown and makes it more portable between flavors. **[md-fixup](https://github.com/ttscoff/md-fixup)** — blank-line spacing, wrapping, table alignment, link normalization, IAL spacing, and dozens of other rules. **Requires command-line comfort.** ```bash brew tap ttscoff/thelab brew install md-fixup md-fixup --overwrite notes.md ``` Note: - Free, open source on GitHub — install with Homebrew: `brew tap ttscoff/thelab && brew install md-fixup` - If you're comfortable on the command line and want to explore this, come back to this slide and view the speaker notes - 36 normalization rules — spacing around lists and code blocks, wrap width, table formatting, reference vs inline links - Handy when you're moving a document between GFM, Kramdown, Pandoc, or Apex and need consistent formatting - Not a GUI — run it in Terminal, hook it into your editor, or use it in CI - Pair with Marked or your editor's preview to check the result after a fixup pass ^^^ ## Inline Attribute Lists (IALs) **Kramdown** and **Apex** — attach IDs, classes, and custom attributes without raw HTML. ```markdown ## Sidebar {: .sidebar} Paragraph with an ID. {: #intro} ![Logo](logo.png){: .center width="200"} ``` Note: - IALs go after the element — `{: .class}`, `{: #id}`, or both - Jekyll blogs use these constantly for styling without inline HTML - Won't work in CommonMark or GFM — Kramdown and Apex territory - We'll come back to Kramdown later — this is the syntax to remember ^^^ ## Fenced divs (`:::`) **Pandoc** and **Apex** — block containers with classes and IDs. ```markdown ::: {.warning} This is a callout box. ::: ::: {#sidebar .note} Sidebar content with an ID and class. ::: ``` [Apex fenced divs syntax](https://github.com/ApexMarkdown/apex/wiki/Syntax#pandoc-fenced-divs) Note: - This is definitely Apex territory - Three or more colons, attributes in braces, content, closing fence - Pandoc pioneered this; Apex supports it in unified mode - Use for warnings, asides, layout regions — more flexible than a blockquote - Wiki link on the slide for the full attribute syntax ^^^ ## A few more worth knowing - **Task lists** (GFM) — `- [x] Done` · `- [ ] Todo` - **Strikethrough** (GFM) — `~~deleted~~` - **Footnotes** (MMD/Apex/Pandoc) — `[^label]` with definition at bottom - **Abbreviations** — `*[HTML]: Hyper Text Markup Language` - **Critic Markup** (Apex) — `{++add++}` `{--del--}` for revision tracking Note: - Quick hits — things you'll see in the wild - Task lists and strikethrough are GitHub bread and butter - Footnotes we cover in academic writing — abbreviations and Critic Markup are niche but handy - These can all be handy but require different flavors, so know what your publishing path uses. --- # One Markdown, Many Flavors Processors interpret the same plain text differently. Note: - Plot twist: there is no single "Markdown standard" - Same `.md` file, different tools, different results — this trips people up - The rest of this section is about picking the right dialect for your project ^^^ | Flavor | Best for | |--------|----------| | **CommonMark** | Spec-compliant, predictable | | **GitHub Flavored** | READMEs, issues, docs | | **MultiMarkdown** | Metadata, footnotes, tables | | **Kramdown** | Jekyll, IAL attributes | | **Markua** | Leanpub books | | **Apex** | Unified processor — all flavors in one | Note: - This is just a Quick cheat sheet, there are way more flavors than just these, but this is a set of ones I find the most useful - CommonMark: the spec baseline — predictable parsing - GFM: GitHub — tables, task lists, strikethrough - MultiMarkdown: metadata, footnotes, citations — big on Mac - Kramdown: Jekyll blogs, inline attribute lists - Markua: Leanpub books - Apex: newer — tries to unify all of the above ^^^ ## Which flavor? 
%%{init: {'flowchart': {'useMaxWidth': true, 'curve': 'linear', 'nodeSpacing': 24, 'rankSpacing': 48}, 'themeVariables': {'fontSize': '15px'}}}%%
flowchart LR
    S(["Project?"]) --> J{"Jekyll?"}
    J -->|Yes| K["Kramdown"]
    J -->|No| G{"GitHub?"}
    G -->|Yes| GF["GFM"]
    G -->|No| L{"Leanpub?"}
    L -->|Yes| MU["Markua"]
    L -->|No| C{"Citations?"}
    C -->|Yes| AC["MMD / Pandoc / Apex"]
    C -->|No| UN["Apex"]
Note: - Decision tree — walk through it with me - Jekyll blog? Kramdown. GitHub README? GFM. Leanpub book? Markua - Need citations and footnotes? MultiMarkdown, Pandoc, or Apex - Not sure? Apex in unified mode is a reasonable default - Most of you will land on one branch in about ten seconds ^^^ ## CommonMark - Formal specification — [commonmark.org](https://commonmark.org) - Predictable parsing (no "surprise HTML") - Foundation for **GitHub Flavored Markdown (GFM)** - GFM adds: tables, task lists, strikethrough, autolinks ```markdown | Column | Column | |--------|--------| | cell | cell | - [x] Done - [ ] Todo ~~strikethrough~~ ``` Note: - Early Markdown had ambiguous parsing — surprise HTML was a real problem - CommonMark fixed that with a formal spec — commonmark.org if you want the details - GFM builds on CommonMark — adds tables, task lists, strikethrough, autolinks - If you live on GitHub, you're already writing GFM ^^^ ## Markua (Leanpub) - Book-oriented Markdown from Leanpub - Chapters, parts, aside boxes, cross-references - Quiz and exercise markup for educational publishing - Extended fenced divs for layout ```markdown # Part One: Getting Started ## Chapter 1: Hello A paragraph with a [footnote]. [^footnote]: Footnote text here. {aside} This sidebar won't appear in all flavors! {aside} ``` Note: - Markua is Leanpub's book dialect — chapters, parts, asides, cross-references - If you're publishing a book on Leanpub, this is your target - Great example of how a flavor extends Markdown for a specific workflow - That aside block? Won't render in CommonMark — flavor matters ^^^ ## Leanpub — write a book, sell it **[Leanpub](https://leanpub.com/)** is a publishing platform built around **Markua** — Markdown for books. - **Special syntax** — notes, asides, page breaks, cross-references, quizzes - **Write in plain text** — preview as you go; publish when ready - **Book output** — EPUB, PDF, and web-readable formats from one manuscript - **Built-in storefront** — sell directly on Leanpub or use their landing pages [Markua Manual](https://leanpub.com/markua/read) Note: - Leanpub is the whole pipeline — not just a Markdown flavor, but a place to write and sell - You write Markua in any editor; Leanpub handles preview, layout, and conversion to book formats - Markua adds book-specific syntax: asides, page breaks, part/chapter structure, instructor notes - One manuscript becomes EPUB for Kindle, PDF for print-on-demand, and a web version - They host the sales page — great for technical books, courses, and indie authors - Marked won't render all Markua on preview, but Leanpub's preview is the target environment ^^^ ## Kramdown & IALs - Default processor for **Jekyll** and many Ruby-based tools - **Inline Attribute Lists** attach classes, IDs, and styles to elements ```markdown * Table of contents {:toc} ## Sidebar {: .sidebar} Paragraph with a custom ID. {: #intro} ![Logo](logo.png){: .center width="200"} ``` Note: - Kramdown is Jekyll's default — if you use Jekyll on GitHub Pages or otherwise, you're on Kramdown unless you've intentionally changed it - IALs — Inline Attribute Lists — attach CSS classes and IDs without raw HTML - `{: .sidebar}` on a heading, `{: #intro}` on a paragraph — powerful for templated sites - Also supports `{:toc}` for auto-generated tables of contents ^^^ ## MultiMarkdown (briefly) - Metadata blocks (title, author, date) - Footnotes, citations, glossaries - Tables, definition lists ```markdown Title: My Document Author: Brett Terpstra Date: 2026-06-24 Doppler shift[^1] is fascinating. [^1]: See any physics textbook. ``` Note: - MultiMarkdown is the Mac writer's friend — metadata at the top, footnotes, citations - nvUltra, MultiMarkdown Composer, and Marked all support it natively - If you've been on Mac and writing Markdown for years, you've probably touched MMD - Metadata block at the top — title, author, date — no YAML delimiters required ^^^ ## Apex — a new contender Unified Markdown processor — CommonMark, GFM, MultiMarkdown, Pandoc, and Kramdown in one tool. - **Unified mode** (default) — best features from every flavor - **Compatibility modes** — `--mode commonmark`, `gfm`, `mmd`, `kramdown` - Fast, C-based — install via Homebrew Note: - Full disclosure — I wrote Apex, so take this with a grain of salt - I built it to alleviate this whole pain of finding the right processor - One processor instead of choosing a flavor and hoping for the best - Unified mode: best features from every dialect; strict modes when you need compatibility - C-based, fast — `brew install` and you're running - Marked doesn't integrate it yet, but you can run it as a custom processor. The goal is to have Marked switched over to using Apex in the next 6 months. - I just released Marked QL, a quick look plugin that does use Apex and is the first step toward getting it into Marked ^^^ ## Apex — unified hub 
flowchart LR
    CM["CommonMark"] --> Apex
    GFM["GFM"] --> Apex
    MMD["MultiMarkdown"] --> Apex
    KD["Kramdown"] --> Apex
    Apex --> HTML["HTML"]
    Apex --> Pandoc["Pandoc"]
    Apex --> Marked["Marked"]
Note: - Visual version of what I just said — all roads lead to Apex - CommonMark, GFM, MultiMarkdown, Kramdown feed in - HTML out, Pandoc integration, Marked preview — one toolchain - Pick a compatibility mode when your publisher or platform requires strict behavior ^^^ ## Apex — syntax highlights - **Tables** — relaxed parsing, captions, rowspan/colspan - **Footnotes** — multiple syntaxes supported - **Math** — LaTeX inline (`$...$`) and display (`$$...$$`) - **Wiki links** — `[[Page Name]]` and `[[Page|Display]]` - **Callouts** — Bear/Obsidian-style `> [!NOTE]` blocks - Abbreviations and GitHub emoji Note: - Day-to-day writing features — the stuff you actually reach for - Tables with captions, footnotes in multiple syntaxes, LaTeX math - Wiki links for Obsidian refugees, callouts like Bear and Obsidian use - This is the "just write" layer — not document engineering, just good prose tools ^^^ ## Apex — document features - **Metadata blocks** — YAML, MultiMarkdown, Pandoc - **`[%key]` variables** and `[%key:transform]` in output - **File includes** — `<<[file]`, `{{file}}`, `--combine` - **Citations & bibliography** — multiple syntaxes and formats - Critic Markup, table of contents markers, indices Note: - Document-level features for books, papers, multi-file projects - Metadata transforms — pipe front matter into templates with `[%key]` - Include other files — build a book from chapters on disk - Citations, bibliographies, Critic Markup for revision tracking - TOC markers and index generation for long-form work ^^^ ## Apex — output & resources - Standalone HTML documents (`--standalone`) - Pretty-printed HTML (`--pretty`) - Plugin system and Pandoc integration [apexmarkdown.org](https://apexmarkdown.org) · [Wiki](https://github.com/ApexMarkdown/apex/wiki) Note: - Output side: standalone HTML, pretty-printed HTML, plugins, Pandoc handoff - apexmarkdown.org for the project — wiki has the full syntax reference - If you're curious, grab it from Homebrew and run it on your own files - Marked can use Apex as a processor — try it in the Dingus later --- # Front Matter Many publishing pipelines expect YAML (or TOML) metadata at the top of a file: ```yaml # Wrapped in --- delimiters at the top of the file: title: "My Post" date: 2026-06-24 tags: [markdown, macstock] layout: post ``` Note: - If you blog with Jekyll, Hugo, or Eleventy, you already know this dance - YAML between `---` delimiters at the top of the file — title, date, tags, layout - The static site generator reads those keys and picks the right template - This is why a horizontal rule on line one of your body is dangerous — some tools think it's front matter ^^^ ## Front matter → template 
flowchart LR
    FM["YAML front matter\ntitle · date · layout · tags"] --> T["Template engine"]
    BODY["Markdown body"] --> T
    T --> HTML["Rendered HTML"]
Note: - Front matter plus body plus template equals rendered HTML - Same layout file wraps hundreds of posts — you only change the metadata and the Markdown - Hugo, Jekyll, Eleventy all work this way — write Markdown, template does the chrome --- # Academic Writing ## Markdown for papers, theses, and research Scholarly work needs more than headers and links — footnotes, citations, bibliographies, and equations. Note: - Markdown isn't just for READMEs and blog posts - Anyone writing papers, theses, dissertations — this section is for you - You need footnotes, citations, bibliographies, equations — Markdown can do all of that - These tools compete seriously with Word for academic workflows ^^^ ## Three strong options on Mac - **MultiMarkdown** — metadata, footnotes, citations, glossaries - **Apex** — unified processor with MMD compatibility + extras - **Pandoc** — convert to PDF, LaTeX, DOCX, and journal formats - **Quarto** and **RMarkdown** Note: - Three tools I recommend on Mac — you'll use one or a combination - MultiMarkdown: metadata, footnotes, citations — the Mac classic - Apex: MMD-compatible plus extras — indices, Critic Markup, more citation syntaxes - Pandoc: the Swiss Army knife — PDF via LaTeX, DOCX with CSL styles for journal submission ^^^ ## The academic pipeline 
flowchart LR
    A[".md draft"] --> P["MMD / Apex / Pandoc"]
    B[".bib library"] --> P
    P --> F["Footnotes & citations"]
    P --> PDF["PDF via LaTeX"]
    P --> DOCX["DOCX via CSL"]
Note: - Your draft in Markdown, your references in a `.bib` file from Zotero - Processor handles footnotes, citations, bibliography formatting - Out comes PDF via LaTeX for print-quality, or DOCX with the citation style your journal requires - Draft in plain text, export in the format your advisor or journal demands ^^^ ## Footnotes Essential for academic prose — keep the main text clean. ```markdown Relativity changed physics forever.[^einstein] [^einstein]: Einstein, A. (1905). *Annalen der Physik*. ``` - **MultiMarkdown** — `[^label]` reference syntax - **Apex** — multiple footnote syntaxes (MMD-compatible) - **Pandoc** — footnotes and inline notes Note: - Footnotes keep the main text clean — reference in prose, detail at the bottom - MultiMarkdown syntax: `[^label]` in text, definition at the bottom - Preview them live in Marked — switch to MultiMarkdown or Apex processor - Pandoc has its own footnote syntax too if you're going that route ^^^ ## Citations & bibliographies Reference a `.bib` file or cite inline — let the processor format the output. | Tool | Approach | |------|----------| | **MultiMarkdown** | Metadata + inline citations, bibliographies | | **Apex** | Multiple citation syntaxes & bibliography formats | | **Pandoc** | `--citeproc` + CSL styles, BibTeX, Zotero export | ```markdown As shown by Smith [-@smith2024], results vary. ``` Note: - Export your library from Zotero with Better BibTeX — `.bib` file on disk - Cite inline in Markdown — processor formats the bibliography - Pandoc shines here: `--citeproc` plus CSL styles for journal-specific formatting - Apex and MMD handle simpler bibliography workflows without the full Pandoc pipeline ^^^ ## Math — inline & display Write equations in LaTeX; render with **MathJax** or **KaTeX** in preview and export. Inline: `$E = mc^2$` Display: ```markdown $$ \int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2} $$ ``` Note: - Two forms: inline math in a sentence, display math on its own line - Inline: `$E = mc^2$` — variables and short expressions in prose - Display: double dollar signs for standalone equations - Marked renders these with MathJax or KaTeX in the preview — you'll see them live ^^^ ## Math by processor | Tool | Approach | |------|----------| | **MultiMarkdown** | LaTeX math with configurable delimiters | | **Apex** | `$...$` inline, `$$...$$` display | | **Pandoc** | Native LaTeX math; export to PDF via LaTeX engine | Note: - All three handle LaTeX math — delimiters differ slightly - Apex: dollar signs inline, double dollars for display — simple - For print-quality PDF, Pandoc through LaTeX is still the gold standard - Marked previews math live regardless — great for checking before you export ^^^ ## Apex for scholars Shared academic features — plus a few Apex-specific extras: - **Indices** — mark terms, generate a back-of-book index - **Syntax highlighting** — fenced code blocks with language tags - **Critic Markup** — `{++add++}`, `{--del--}`, `{~~old~>new~~}` for revisions - **Table of contents** — `{:toc}`, `{{TOC}}` markers Apex handles drafting and HTML; pair with **Pandoc** for final PDF or DOCX when needed. Note: - Indices for textbooks and theses — mark a term, generate a back-of-book index - Critic Markup for advisor review: `{++add++}`, `{--del--}`, `{~~old~>new~~}` — track changes in plain text - Apex for drafting and HTML preview; hand off to Pandoc when you need final PDF or DOCX - If your thesis has code appendices, syntax highlighting matters too --- # Writing Apps for Mac Note: - We've covered Markdown-first apps — now editors and tools for every workflow - Show of hands: what are you using today? nvUltra? VS Code? BBEdit? - There's no single right app — pick what fits your brain ^^^ ## Native & Mac-first - **[nvUltra](https://nvultra.com/)** — fast, MultiMarkdown-native, search-focused · *ask Brett for a beta invite* - **[MultiMarkdown Composer](https://multimarkdown.com/composer/)** — structured long-form writing · *ask Brett about a v5 beta invite* - **[Typora](https://support.typora.io/Typora-on-macOS/)** — seamless WYSIWYG Markdown editing - **[Lettera](https://lettera.md/)** — rich-text-like editing, live rendering · *TestFlight; beta full for now* - **[iA Writer](https://ia.net/writer)** — focused drafting (also listed earlier) - **[One Markdown](https://apps.apple.com/us/app/one-markdown/id1507139439)** — clean, minimal · Mac and iOS - **[Byword](https://www.bywordapp.com/)** — older but sturdy · Mac and iOS Note: - nvUltra: searchable portable MultiMarkdown notes — private beta, ask me for an invite — nvultra.com - MultiMarkdown Composer: native MMD editor from Fletcher Penney — v5 beta available, ask me - Typora: WYSIWYG Markdown, deeply integrated with macOS - Lettera: from the Bear team — TestFlight beta; waitlist at lettera.md — beta is full for now - iA Writer: Focus Mode, syntax highlight, cross-platform — ia.net/writer - One Markdown: TextBundle editor — free on Mac App Store and iOS - Byword: been around forever, still solid — syncs via iCloud/Dropbox, exports to Medium, WordPress, and more - If you want footnotes and metadata without thinking about it, nvUltra or MMC ^^^ ## Already using Markdown? If you use **Bear**, **Obsidian**, **Ulysses**, or **NotePlan** — you're set. Add **Marked** for live preview and export from any of them. Note: - Circle back to the apps we opened with — Bear, Obsidian, Ulysses, NotePlan - They all write Markdown natively — you're already set - Add Marked on the side: it watches your files and shows rendered output - You keep your favorite editor; Marked handles preview and export ^^^ ## Developers & power users - **VS Code** — extensions for preview, linting, snippets - **Sublime Text** + MarkdownEditing - **TextEdit** — yes, really (plain text mode) - **BBEdit** — grep, clippings, syntax-aware editing Note: - VS Code: extensions for preview, linting, snippets — huge ecosystem - Sublime Text plus MarkdownEditing — still a favorite for many - TextEdit in plain text mode — yes, really — underrated for quick edits - BBEdit: grep, clippings, batch find-and-replace across folders — a workhorse --- # Publishing Paths 
flowchart LR
    A["Write (.md)"] --> B["Process"] --> C["Publish"]
    B --> D["HTML / PDF / EPUB / DOCX / RSS"]
Note: - The big picture: write Markdown, run it through a processor, publish somewhere - The processor and template determine what comes out the other end - Same source file — HTML for the web, PDF for print, EPUB for ebooks, DOCX for Word, RSS for feeds - Everything we've talked about feeds into this pipeline ^^^ ## Static Site Generators **Jekyll** (Ruby) — GitHub Pages default ```bash # _posts/2026-06-24-my-post.md bundle exec jekyll serve ``` **Hugo** (Go) — blazing fast builds ```bash # content/posts/my-post.md hugo server -D ``` Note: - Two popular static site generators — both Markdown plus front matter plus templates - Jekyll: Ruby, GitHub Pages default, Kramdown processor — `_posts` folder, `bundle exec jekyll serve` - Hugo: Go, blazing fast, Goldmark processor — `content/posts`, `hugo server -D` - Great for blogs, docs, portfolios — no database, no WordPress overhead ^^^ ## SSG build pipeline 
flowchart LR
    A[".md + front matter"] --> B["Build\nJekyll / Hugo"]
    B --> C["_site/"]
    C --> D["GitHub Pages\nNetlify\nDreamhost"]
Note: - Write locally, build to a folder of static HTML, deploy that folder - Jekyll or Hugo reads your Markdown, applies templates, outputs `_site` - Push to GitHub Pages, Netlify, Dreamhost — anywhere that serves static files - No server-side rendering at request time — fast, cheap, secure ^^^ ## Blogging with Markdown **MarsEdit** — native Mac blog editor - Works with WordPress, Micro.blog, Ghost, and more - Write in Markdown, preview before publish - Integrates with Marked for live preview **WordPress + Jetpack** - Enable Markdown in Jetpack settings - Write in the block editor or Classic - Jetpack converts Markdown → HTML on save Note: - If you blog, you don't have to leave Markdown behind - MarsEdit: native Mac app — WordPress, Micro.blog, Ghost, and more — write in Markdown, preview, publish - MarsEdit integrates with Marked for live preview as you write - WordPress plus Jetpack: enable Markdown in settings — write Markdown, Jetpack converts on save ^^^ ## Blogging paths 
flowchart TD
    MD["One .md draft"] --> ME["MarsEdit"]
    MD --> SSG["Static site"]
    MD --> BLOT["Blot + Dropbox"]
    ME --> WP["WordPress"]
    ME --> MB["Micro.blog"]
    ME --> GH["Ghost"]
    SSG --> HOST["Static host"]
Note: - One Markdown draft — many paths to publication - MarsEdit out to WordPress, Micro.blog, or Ghost - Static site generator out to GitHub Pages or Netlify - Blot: drop a file in Dropbox, it's a blog post — dead simple - Pick the path that matches how you already work ^^^ ## Other destinations - **Micro.blog** — Markdown-native social blogging - **Ghost** — Markdown in the editor - **Blot** — Dropbox folder → blog - **Pandoc** — Swiss Army knife format conversion Note: - Micro.blog: Markdown-native, social, short-form — great for Mac users - Ghost: Markdown in the editor, modern publishing platform - Blot: literally a folder in Dropbox — save Markdown, it's live - Pandoc: when someone asks "how do I get Markdown into EPUB or LaTeX?" — `pandoc input.md -o output.epub` --- # What Do You Call Someone Who Only Reads 12.5% of the Bible? # An eightheist. --- # Marked 3 ## The Ultimate Markdown Preview [markedapp.com](https://markedapp.com) Note: - Now the main event — Marked 3, markedapp.com - Full disclosure again: I make this app — but we're going to demo it because it's a good way to tie everything together - Live preview from any editor, export, Dingus — this is what we'll play with in the workshop - There's a metric ton of functionality we're not going to cover, but if you want to explore and ask questions during the workshop period, I'll be happy to answer ^^^ ## Live Preview - Watches files as you edit in **any** app - Scroll sync, source map click-to-line - Multiple documents, tabbed windows - Works with Scrivener, Word, MarsEdit, Ulysses, and more Note: - Marked doesn't replace your editor — it augments it - Write in nvUltra, VS Code, BBEdit, Ulysses — Marked watches the file and updates the preview - Scroll sync, click a paragraph in the preview to jump to that line in the source - Tabbed windows, multiple documents — keep several files open at once ^^^ ## How live preview works 
sequenceDiagram
    participant Editor
    participant File as .md file
    participant Marked
    participant Processor
    Editor->>File: Save
    File->>Marked: File change detected
    Marked->>Processor: Run processor
    Processor->>Marked: HTML output
    Marked->>Marked: Update preview
Note: - The loop: you save in your editor, Marked detects the change, runs the processor, updates the preview - That's it — no copy-paste, no manual refresh - From there you can export to PDF, EPUB, DOCX, or just keep previewing ^^^ ## Processors in Marked Switch processors to see how flavors differ: - **Discount (GFM)** - **MultiMarkdown 5** - **CommonMark** - **Kramdown** Custom Processors + Custom Rules for transforms and shell commands. Note: - This is where flavors become visible — switch processors in Marked and watch the output change - Discount for GFM, MultiMarkdown 5, CommonMark, Kramdown — all built in - Custom Processors let you plug in Apex, Pandoc, anything with a CLI - Custom Rules for find-and-replace transforms on the source or output - Sets up the Dingus demo coming up — same text, different processors ^^^ ## Export & Publish Export to: - **PDF** — print-ready, custom CSS - **HTML** — standalone or snippet - **EPUB** — e-books with custom styles - **DOCX / RTF** — Word workflows, change tracking - **Markdown** — normalized output Export Profiles save your preferred settings. Note: - Export is where preview becomes deliverable - PDF with custom CSS — print-ready, your fonts, your layout - EPUB for ebooks, DOCX for Word workflows and track changes - Export Profiles save your settings — one click to reproduce your preferred output - If time allows I'll demo a quick PDF export with a custom style ^^^ ## Export from the keyboard **⇧⌘E** opens Marked's **Export palette** - Type a few characters — `pdf`, `epub`, `docx` — to filter formats - Arrow keys to select, Return to export — no menus, no mouse - Export Profiles appear in the list too Note: - Shift-Command-E — Export palette - Start typing: "pdf", "epub", "html" — filters instantly - Entire export workflow from the keyboard — preview, palette, return, done - Great when you're iterating on a draft and exporting repeatedly - Saved Export Profiles show up — type part of the profile name ^^^ ## Action palette **⇧⌘P** opens Marked's **Action palette** - Every menu item in one searchable list - Type to filter — "style", "processor", "markdownify", "copy" - Run any command without hunting through menus Note: - Shift-Command-P — same muscle memory as VS Code's command palette - Every Marked menu item, searchable - Can't remember where Style Stealer lives? Type "style steal" - Switch processors, open preferences, run exports — all from the keyboard - Once you learn it, you rarely touch the menu bar ^^^ ## Markdownify a URL **File → New → Markdownify URL** (`⌘K`) Paste any article or blog post URL — Marked fetches the page and converts it to **clean Markdown**. - Great way to **start playing** — real content, not a blank file - Strip ads and cruft; edit what you get - Browser extensions available too — but built-in is fastest on Mac Note: - File, New, Markdownify URL — Command-K - Paste any article URL — Marked fetches the page and gives you clean Markdown - Strip the ads and cruft, edit what you get — great way to start playing in the workshop - Browser extensions exist, but built-in on Mac is fastest — no context switching ^^^ ## Style Stealer **Style → Style Stealer** Point Marked at your live blog (or any site) and **capture its typography and layout** for preview and export. - Match your published look while drafting - One click — no hand-writing CSS from scratch - **Style Generator** — refine what Style Stealer captured; tweak fonts, spacing, and colors until it's right Note: - Style Stealer: point at your live blog or any site — capture typography and layout - One click — your preview and exports match your published look, not generic defaults - Style Generator: refine what Stealer captured — tweak fonts, spacing, colors until it's right - Pair with export — PDF and HTML that look like your site ^^^ ## Demo: MacStories style + Markdownify Note: - **Pause the slideshow here** - Open Marked: Style, Style Stealer — capture macstories.net styling - Then File, New, Markdownify URL — Command-K — paste a MacStories article URL - You get MacStories typography plus real article content ^^^ ## Long-form reading Marked is built for **reviewing long documents** — not just quick previews. - **Table of Contents** — jump by heading; **Fast Search** type-ahead navigation - **Bookmarks** — mark spots to return to while editing - **Autoscroll** - Hit `S` to scroll at your selected WPM - **Speed Read** — RSVP overlay for focused read-throughs Note: - Long manuscripts, theses, book chapters — Marked handles more than blog posts - TOC sidebar: click a heading to jump; Fast Search lets you type ahead to filter headings instantly - Bookmarks: flag a section, come back after you've edited elsewhere - Speed Read mode: RSVP overlay — word-by-word if you want to review prose without scrolling - Great combo: bookmark while reading, jump to source to edit, export when ready ^^^ ## Proofreading & Tools - Grammar and style checking - Wiki navigation with backlinks - TextBundle / TextPack import & export - Document statistics (⌘I) Note: - Beyond preview and reading — Marked has proofreading and utility tools - Grammar and style checking built in - Wiki navigation with backlinks, TextBundle import and export - Show your character and word count, sentence count, and Fog and grade level reading scores - Adjustable reading speed for calculating reading time --- # How Do You Find Will Smith in the Snow? Look for fresh prints. --- # Markdown Dingus ## Let's see it in action Open Marked → **Help** → **Markdown Dingus** - Live preview as you type - Switch processors: Discount, MultiMarkdown 5, CommonMark, Kramdown - Compare output side by side Note: - **Demo time** - **Help -> Open Markdown Dingus** — live preview as you type - Switch processors and watch the same snippet render differently - Pay attention to Kramdown IALs and MMD metadata — they appear or vanish depending on processor ^^^ ## Try this in the Dingus ```markdown # Hello, Macstock! **Bold** and *italic* — processor-agnostic. [With a link](https://brettterpstra.com) | Flavor | Use case | |-----------|---------------| | CommonMark| Spec baseline | | Kramdown | Jekyll blogs | ## Styled Block ## {: .highlight} A Kramdown IAL on the heading above. ``` Note: - Paste this snippet in the Dingus — it's your workshop handout - Flip between CommonMark, Kramdown, MultiMarkdown and watch what changes - The IAL on "Styled block" only works in Kramdown — CommonMark ignores it - Attendees following along: this is your starting point for the workshop ^^^ ## Markdown Dingus Shortcuts ## - ⌘I/⌘B for italics and bold - Ctrl-cmd up/down/left/right to move and indent/outdent lines - ⌘K to insert a link - F6 with selection to create a magic link, F7 to create a footnote - Check out the [Dingus docs](https://markedapp.com/help/Markdown_Dingus#editinginthedingus) --- # Workshop Time ## ~45 minutes — play, experiment, ask questions 1. Open **Help** → Open Markdown Dingus 2. Paste the sample snippet (previous slide) 3. Switch processors — watch what changes 4. Try your own Markdown 5. Raise a hand — I'll come around! Note: - Workshop time — about 45 minutes to play - Open Marked, open the Dingus, paste the sample snippet from the last slide - Switch processors, try your own files, experiment with export - Raise a hand and I'll come around — blogging setups, export questions, whatever you've got - I'll keep the Dingus on screen at the front for reference ^^^ ## Workshop ideas - Bring a `.md` file from your blog or notes, or capture one with the Markdownifier - Try exporting to PDF or EPUB with a custom style - Test Kramdown IALs for a Jekyll/Hugo site - Set up Marked to watch your editor of choice - Ask about MarsEdit + WordPress workflows Note: - Ideas if you're not sure where to start - Bring a `.md` file from your blog or notes and open it in Marked - Try Markdownify on a favorite article — Command-K - Steal your blog's style with Style Stealer, export to PDF - Set up Marked to watch nvUltra, VS Code, or whatever you use - Pair up with someone using similar tools — compare notes - See Settings->Applications to set your own editor or use the Dingus --- # Tips & Best Practices - **Pick a flavor** and stick with it per project - **Use front matter** for metadata — don't bury title in the body - **Preview with the same processor** you'll publish with - **Alt text** on images — accessibility matters - **One file per chapter/post** — easier to manage and reuse Note: - Quick wisdom before we wrap - Pick a flavor per project and stick with it — don't mix Kramdown and MMD in one file - Use front matter for title and date — don't bury metadata in the body - Preview with the same processor you'll publish with — surprises on deploy are no fun - Alt text on every image; one file per post or chapter for easier management --- # I did a theatrical performance about puns. It was a play on words. --- # This whole presentation was written in Markdown Every slide — including the Mermaid diagrams — lives in **[slides.md](https://brettterpstra.com/macstock2026/slides.md)**. Follow that link to read the plain-text source in your browser — slide separators, speaker notes, and all. Feel free to copy parts of it and play with it. The slideshow is built with **[reveal.js](https://revealjs.com)** using its [Markdown plugin](https://revealjs.com/markdown/). Note: - Meta moment — this entire talk is one Markdown file - Every slide, every diagram, every note — in slides.md - The link opens raw Markdown in the browser — no view source required - reveal.js loads slides.md at runtime and splits it into slides. It won't work as a slideshow without it. ^^^ ## Marked Help as Markdown ## You can also quickly get some Markdown to play with by going to [the Marked docs](https://markedapp.com/help/), finding an interesting page, and adding .md at the end of the URL. (This works with .txt on Daring Fireball as well.) --- # Advanced Topics Optional depth for power users — not required for everyday Markdown publishing. Note: - Optional section — skip if you're good, listen if you're curious - Not required for everyday Markdown publishing - Git and version control — plain text makes this especially satisfying ^^^ ## Version control with Git Plain text makes versioning especially rewarding: - **Track changes** — see what you wrote last week vs. today - **Revert safely** — undo experiments without losing work - **Branch drafts** — try a rewrite without touching the published version - Every edit is visible in a diff — no opaque binary files **GitHub Desktop** — Mac-friendly GUI, no terminal required Note: - Plain text diffs beautifully — every change visible line by line - See what you wrote last week vs. today; revert a bad experiment safely - Branch a draft rewrite without touching the published version - GitHub Desktop if you don't want the terminal — Mac-friendly GUI - You don't need Git to publish Markdown — but GitHub Pages plus Jekyll is one hosting path if you're already on GitHub ^^^ ## Git workflow 
gitGraph
    commit id: "Published post"
    branch draft
    checkout draft
    commit id: "Rewrite intro"
    commit id: "Add section"
    checkout main
    merge draft id: "Publish v2"
Note: - Branch for experiments, merge when ready - Published post on main, draft rewrite on a branch — intro, new section, merge when happy - Plain text diffs show exactly what changed — no opaque Word binary files - Writing and code share the same workflow — that's the point --- # Resources - [CommonMark Spec](https://commonmark.org) - [Introducing Markdown (2004)](https://daringfireball.net/2004/03/introducing_markdown) - [Kramdown Syntax](https://kramdown.gettalong.org) - [Markua Manual](https://leanpub.com/markua/read) - [Marked Documentation](https://markedapp.com/help) - [MultiMarkdown](https://fletcherpenney.net/multimarkdown) - [Pandoc](https://pandoc.org) - [Apex Markdown](https://apexmarkdown.org) - [Apex Wiki](https://github.com/ApexMarkdown/apex/wiki) ## Questions? **[@ttscoff](https://hachyderm.io/@ttscoff)** [markedapp.com](https://markedapp.com) · [@markedapp](https://indieapps.space/@marked) Note: - Links on screen — CommonMark, Gruber's original post, Kramdown, Markua, Marked docs, MMD, Pandoc, Apex - Marked has a free trial — markedapp.com — try everything we demoed today - Questions? I'm @ttscoff on Mastodon, @markedapp on indieapps.space - Thank you — enjoy the rest of Macstock