Articles
- September 13, 2026
How to Write a README.md People Will Actually Read
Learn how to write a README.md people actually read: what to include, how to structure it, common mistakes to avoid, and a template to start from.
Read - September 12, 2026
YAML Front Matter in Markdown: What It Is and How to Use It
YAML front matter is a fenced block of key-value metadata at the top of a Markdown file — titles, dates, tags — that tools read separately from the body. Here's the syntax, the common pitfalls, and when it's worth adding.
Read - September 11, 2026
Markdown Tables: Syntax, Alignment, and When to Use Them
Markdown table syntax explained: the header row, delimiter row, and colon-based alignment rules, plus when a cell needs HTML instead of GFM markdown.
Read - September 10, 2026
GitHub Issue and Pull Request Templates in Markdown: A Practical Setup
Issue templates are Markdown files in .github/ISSUE_TEMPLATE/, pull request templates are a single PULL_REQUEST_TEMPLATE.md — here's exactly where each one goes, what frontmatter it needs, and how to add a chooser once you have more than one.
Read - September 9, 2026
One Sentence Per Line: Writing Markdown That Diffs Cleanly in Git
A hard-wrapped paragraph turns a one-word edit into a six-line diff. Writing one sentence per line fixes that — and it renders exactly the same. Here's how the convention works and how to start using it.
Read - August 30, 2026
Markdown vs AsciiDoc vs reStructuredText: Picking Plain Text
Markdown, AsciiDoc, and reStructuredText are all plain-text markup, but they solve different problems. Here's how their syntax, built-in features, and typical use cases compare — and when the extra structure of AsciiDoc or reST is actually worth it.
Read - August 29, 2026
Markdown Footnotes: GFM vs. Pandoc Syntax Compared
Footnotes aren't part of core CommonMark, so GFM and Pandoc each built their own version. Here's exactly where the syntax overlaps, where it diverges, and which pattern survives a move between renderers.
Read - August 28, 2026
Automate Note Capture on iPhone with the Shortcuts App
Turn note-taking on iPhone into a trigger, not a task. Set up Shortcuts automations, the Action Button, and clipboard capture so notes save themselves.
Read - August 27, 2026
How to Turn Markdown into Slide Decks with Marp
Marp converts a plain Markdown file into a slide deck using one extra rule: a horizontal ruler to mark where each slide ends. This guide covers writing the deck, converting it to HTML, PDF, or PowerPoint with Marp CLI, styling it with themes, and where Marp fits next to other Markdown presentation tools.
Read - August 26, 2026
Markdown in Slack and Discord: Why Your Formatting Doesn't Match
Paste Markdown into Slack and bold disappears. Paste it into Discord and headings vanish. Here's why — Slack runs two different formatting dialects, Discord adds its own syntax, and neither is 'broken.'
Read - August 25, 2026
Markdown Keyboard Shortcuts for Faster Writing on Mac
Command+B, Command+I, Command+K, and Command+E map to Markdown bold, italic, link, and code on Mac. Here's how each shortcut works and when it's worth using.
Read - August 24, 2026
Markdown Emoji Shortcodes: Syntax and Platform Support
Typing :+1: or :shipit: in a GitHub comment turns into an emoji -- but that colon-wrapped shortcode syntax is not part of the CommonMark or GitHub Flavored Markdown specification. It is a rendering-layer convenience GitHub, Slack, and Discord each implement with their own shortcode tables, which is why the same emoji can resolve under different codes on different platforms. This piece walks through how the syntax works, why it sits outside the formal spec, where support falls apart, and when a literal Unicode emoji character is the more portable choice.
Read - August 23, 2026
Math Equations in Markdown: LaTeX Syntax with KaTeX and MathJax
Markdown has no built-in math syntax — equations come from LaTeX written between $ or $$ delimiters, rendered client-side by KaTeX or MathJax. Here's the syntax, the trade-offs between the two renderers, and when it's actually worth setting up.
Read - August 22, 2026
How to Write AI Context Files in Plain Text and Markdown
AI context files like AGENTS.md, CLAUDE.md, and llms.txt are just plain Markdown. Here's the format, the common conventions, and what to leave out.
Read - August 21, 2026
Why Markdown Strips Raw HTML (and What to Use Instead)
CommonMark lets raw HTML pass through by default, but GitHub Flavored Markdown strips some of it for security. Here is the native syntax to use instead.
Read - August 20, 2026
README Badges: Build Status, License, and Version at a Glance
Add README badges for build status, license, and version in seconds. See the exact Markdown syntax, URL patterns, and where each one belongs.
Read - August 19, 2026
GFM Autolinks Explained: When Plain URLs Become Clickable Links
GitHub Flavored Markdown's autolinks extension turns a bare URL, a www. address, or an email sitting in plain text into a clickable link with no [text](url) syntax. This explainer covers the three extended autolink types, the trailing-punctuation trimming rules, and when writing out an explicit link is still the better call.
Read - August 18, 2026
Migrating to Plain-Text Notes from a Formatted Notes App
Moving to plain text means exporting your notes, converting formatting into Markdown syntax, and deciding what's worth keeping. Here's the actual step-by-step, plus the fixes for the parts that usually go wrong.
Read - August 17, 2026
Managing Citations and Bibliographies in Markdown with Pandoc
Write citation keys inline as you draft, then let Pandoc turn them into formatted in-text citations and a bibliography — here's the syntax, the file formats it reads, and the fixes for the problems that come up.
Read - August 16, 2026
Nested Task Lists in Markdown: Indentation That Works Across Every Renderer
Nested checkboxes have no special syntax of their own — they follow CommonMark's general list-nesting rule. Here's the indentation that renders correctly everywhere, and why a 2-space habit quietly breaks.
Read - August 15, 2026
Markdown Code Blocks with File Names and Line Numbers: A Practical Convention
There's no official Markdown syntax for filenames or line numbers in a code block. Here's the convention that works across renderers, and where it breaks.
Read - August 14, 2026
How to Write a CONTRIBUTING.md People Will Actually Follow
Most CONTRIBUTING.md files get written once and ignored forever. Here's what actually makes contributors read one: specific asks, exact setup steps, and a file placed where GitHub surfaces it automatically.
Read - August 13, 2026
Definition Lists and Other Markdown Extras Most Editors Skip
Definition lists, footnotes, and sub/superscript aren't in core Markdown. Here's the exact syntax for each and why your editor might not render them.
Read - August 12, 2026
How to Sync Plain-Text Notes Across iPhone, iPad, and Mac
Turning on iCloud Drive lets any plain-text or Markdown note you write on iPhone, iPad, or Mac stay in sync everywhere else automatically. This guide walks through setup on every device, what actually happens when two devices edit the same file offline, how to fix the version conflict that results, and when a git-based workflow is worth the extra manual step over automatic syncing.
Read - August 11, 2026
Why the Same Markdown File Renders Differently Everywhere
Markdown was never one standardized language. Every app implements its own dialect on top of a loosely defined original description, so the same file can render one way on GitHub and another way in your editor. Here's why, and how to write around it.
Read - August 10, 2026
Tags vs Folders: Picking (or Combining) a Note System
Folders and tags solve different problems, not the same one. Here's what the research says about why people default to folders, where tags earn their keep, and a hybrid convention that keeps both useful as your notes grow.
Read - August 9, 2026
A Tag Naming System That Won't Fall Apart as Notes Grow
Tags feel effortless with ten notes and chaotic with a thousand — not because tagging is a bad idea, but because nobody agreed on a naming convention before the collection grew. This piece lays out the delimiter, singular/plural, and prefix rules that keep a tag list searchable no matter how large it gets, plus a quarterly cleanup habit that keeps it that way.
Read - August 8, 2026
SSH Config Files on Mac: How to Write and Organize Yours
Your Mac doesn't ship with an SSH config file — you write it yourself. This guide covers the ~/.ssh/config syntax, the permissions SSH insists on, macOS Keychain integration, and how to organize Host aliases so multiple servers and accounts don't collide.
Read - August 7, 2026
Why Your Code Snippets Belong in Plain Markdown Files
A dedicated snippet manager isn't the only way to keep reusable code organized. A plain Markdown file with fenced code blocks gives you syntax highlighting, full-text search, and something most snippet managers can't: a file you can open, grep, or back up decades from now without an export step.
Read - August 6, 2026
How to Convert a Spreadsheet or CSV into a Markdown Table
Spreadsheets don't write Markdown natively, so getting a table of data into a Markdown file means exporting to CSV first, then converting — by hand for a short table, with Pandoc for anything larger. Here's the syntax, the command, and the mistakes that break rendering.
Read - August 5, 2026
Do You Still Need a Snippet Manager With AI Coding Assistants?
GitHub Copilot and Cursor now carry context across a session, and Copilot Memory adds persistent repo facts on top. That covers a lot of what a snippet manager used to do — but not team sharing, presentation, offline work, or simply owning your own reference material.
Read - August 4, 2026
How to Version-Control Your Markdown Notes with Git
Git isn't just for code. A folder of Markdown notes under version control gives you a full history of every draft, a way to compare changes, and an easy way back to any earlier version — using the same handful of commands developers already rely on.
Read - August 3, 2026
GitHub Markdown Alerts: NOTE, TIP, and WARNING Explained
GitHub's alert syntax turns a plain blockquote into a colored, iconed callout with a line like [!NOTE] or [!WARNING]. It's useful, but it's a GitHub-specific extension, not standard Markdown — here's the exact syntax, all five alert types, and where the formatting quietly breaks.
Read - August 2, 2026
Writing API Documentation in Markdown: A Practical Structure
A repeatable per-endpoint structure for API docs in plain Markdown: endpoint definition, parameter table, request example, response example — plus the fenced-code-block rules that make the samples render correctly.
Read - July 30, 2026
From Markdown to Published: A Git-Based Blogging Workflow
Write a post as plain Markdown, add front matter, commit it, and push. Here's what actually happens between your file and a published page — and where it breaks.
Read - July 27, 2026
How to Add Comments in Markdown (That Never Render)
Markdown was never given a comment syntax, so writers reuse two side effects instead: an HTML comment and a link-reference line. Both hide text from the rendered page — here's how each one works, where they break, and which one to reach for.
Read - July 26, 2026
A Plain-Text Zettelkasten: Linking Notes Without a Special App
The Zettelkasten method is a linking discipline, not a piece of software. Atomic notes, stable IDs, and text-reference links do the whole job — here's how to run one in a folder of plain Markdown files, and how to find your backlinks with a single grep command.
Read - July 25, 2026
How to Build a Table of Contents in Markdown with Anchor Links
A Markdown table of contents is just a list of links pointing at auto-generated heading anchors. Here's exactly how those slugs are built, what breaks them, and how to keep every link working.
Read - July 24, 2026
How to Keep a CHANGELOG.md Your Team Will Actually Read
How to keep a CHANGELOG.md in markdown that your team actually reads: the six standard change categories, the Unreleased section, ISO dates, and how to avoid a wall of commit messages.
Read - July 23, 2026
How to Add Mermaid Diagrams to Your Markdown Files
A Mermaid diagram is just a fenced code block of plain text. Here's the exact syntax for a flowchart, why it beats a pasted-in image, and how to fix the most common rendering mistakes.
Read - July 22, 2026
Markdown Heading Levels: ATX vs Setext Explained
Markdown gives you two ways to write a heading: hash marks in front of the text, or an underline beneath it. They aren't interchangeable — one supports six heading levels, the other only two. Here's the exact syntax for both, where each comes from, and which one to reach for in your own notes and docs.
Read - July 21, 2026
Inline Code vs. Code Blocks in Markdown: When to Use Each
Markdown gives you two ways to show code: a short inline span for a term inside a sentence, and a fenced block for a standalone snippet. Mixing them up makes docs harder to read. Here's the rule for picking the right one, how the syntax works, and where syntax highlighting fits in.
Read - July 20, 2026
Capture Ideas on iPhone: A Fast Plain-Text Inbox
A single running plain-text file beats a folder full of formatted notes when the goal is speed. Here's how to build a fast, low-friction capture inbox on iPhone, and why plain text is what makes it durable.
Read - July 19, 2026
Daily Notes: A Plain-Text Journaling Habit That Sticks
Most daily-notes habits fail from too much structure, not too little. This guide covers a minimal plain-text template, how to anchor the habit to an existing routine, and why Markdown outlasts proprietary journaling formats.
Read - July 18, 2026
iPad Split View and Multitasking Shortcuts for Writers
iPadOS 26 rebuilt multitasking around resizable windows and Stage Manager on every supported iPad. Here's how to open Split View with a keyboard shortcut, group a writing-plus-reference setup you can reuse, and fix the layouts that don't stick.
Read - July 17, 2026
Writing Technical Docs in Markdown: A Style Guide
A practical Markdown style guide for technical docs: heading hierarchy, code fences, tables, task lists, and link conventions that keep docs consistent.
Read - July 16, 2026
Markdown vs Rich Text: Why Writers Choose Plain Text
Rich text editors hide formatting behind menus and proprietary encoding; Markdown keeps it visible as plain text. Here's the real difference between Markdown and rich text formats like RTF and Word, where rich text quietly loses data, and why plain text files hold up better over time.
Read - July 15, 2026
Markdown Horizontal Rules: Dividers for Long Notes
Three dashes, three asterisks, or three underscores on their own line make a Markdown divider. Here's the exact syntax, the two ways it silently breaks, and when a divider actually earns its place in a long note.
Read - July 14, 2026
Markdown Bold, Italic, and Strikethrough: The Complete Emphasis Guide
Markdown bold, italic, and strikethrough all come down to matching a marker at the start and end of your text. This guide covers the exact syntax for each, how to combine bold and italic, why strikethrough only works in some renderers, and the common mistakes — stray spaces, mismatched markers, accidental mid-word emphasis — that break the formatting.
Read - July 13, 2026
Markdown Line Breaks: Why Your Text Runs Together (and How to Fix It)
You typed two lines and got one run-together sentence. That's not a bug — Markdown treats a single newline as a soft break by design. This guide covers why, the two ways to force a real hard break (trailing spaces vs. backslash), the <br> tag option, and the GitHub quirk that makes formatting look different in a comment than in a README.
Read - July 12, 2026
Nested Lists in Markdown: Indentation Rules That Work
Nested lists are the most common way Markdown quietly breaks. The fix isn't memorizing '4 spaces' — it's aligning each sublist with the first character after its parent marker. This guide covers the rule, the marker-width math, and the code-block and blockquote edge cases that trip people up.
Read - July 11, 2026
Keep Markdown Consistent: Linting and Formatting Your Files
Markdown has no single canonical style, so heading choices, list indentation, and stray whitespace drift apart the longer a set of files grows. Here's why that happens, how a linter like markdownlint catches it, and which rules are worth enforcing first.
Read - July 10, 2026
Scratch Files: The Case for a Throwaway Plain-Text Buffer
A scratch file is a temporary, usually unnamed plain-text or code buffer for jotting something down before you know whether it's worth keeping. Here's what they're for, how different editors implement them, and when to promote one into a real file.
Read - July 9, 2026
How to Search Across Your Notes with grep and ripgrep
Your notes are plain text, so you already have a fast search tool sitting on your machine: the terminal. This guide covers grep and ripgrep basics, the flags worth knowing, and how to fix the most common search problems in a notes folder.
Read - July 8, 2026
How to Export Markdown to PDF and Word with Pandoc
Two pandoc commands turn a Markdown file into a Word document or a PDF. Here's the exact syntax, the PDF engine pandoc needs, how to style the Word output with a reference template, and the fixes for the problems that show up first.
Read - July 7, 2026
A Plain-Text Meeting Notes Template You'll Actually Reuse
One plain-text skeleton — a header block, headings per agenda item, and Markdown task-list checkboxes for action items — that you reuse for every meeting instead of reinventing the format each time.
Read - July 6, 2026
Markdown Blockquotes and Callouts: Syntax, Nesting, and When They Break
A Markdown blockquote is just a > at the start of a line, but it can nest, hold headings and code, and even power GitHub-style callouts like [!NOTE]. This how-to covers the syntax, the common blank-line mistake that splits a quote in two, and how callouts degrade gracefully in plain text.
Read - July 4, 2026
Escaping Special Characters in Markdown: A Backslash Guide
A backslash escape turns a Markdown character back into plain text — but only in some places. This guide covers the full CommonMark escapable set, why backslashes are inert inside code spans, the trailing-backslash line-break exception, and platform quirks on GitHub and Apple's own markup.
Read - July 3, 2026
How to Convert Word and Google Docs to Markdown with Pandoc
Google Docs and Word files don't leave Markdown behind on their own. This walks through the exact Pandoc command that gets you there, how to pull out embedded images, and the fixes for the tracked-changes and table problems that show up along the way.
Read - July 2, 2026
Markdown Links and Images: Inline vs Reference Style, and When to Use Each
Markdown lets you write links and images two ways: inline, with the URL right next to the text, or reference-style, with a short identifier resolved by a separate definition. This explainer covers both syntaxes precisely, the CommonMark spec's full/collapsed/shortcut forms, and a practical rule for when each style actually helps.
Read - July 1, 2026
How to Edit Config Files and Dotfiles Quickly on Mac and iOS
Config files and dotfiles are just plain text, so any fast editor can open them. Learn to reveal hidden files, edit .gitignore, set a global ignore, and stay consistent with .editorconfig on Mac and iOS.
Read - June 30, 2026
Capture Now, Organize Later: A Plain-Text Note-Taking System That Sticks
Capture everything fast into one plain-text inbox, then organize later in Markdown. A note-taking system that stays low-friction, portable, and future-proof.
Read - June 29, 2026
Outlining Long Documents in Markdown: Headings That Stay Navigable
A long Markdown file is only as usable as its headings. Here is how to build a heading hierarchy that doubles as your outline and your navigation — so a 4,000-word document stays easy to scan, link, and edit.
Read - June 28, 2026
YAML Front Matter Explained: Adding Metadata to Your Markdown Files
YAML front matter is the small block of metadata at the top of a Markdown file, fenced by triple dashes. It stores things like title, date, and tags without cluttering your text. Here's how the syntax works, which fields you'll actually use, and when front matter earns its place in your files.
Read - June 26, 2026
Task Lists and Checkboxes in Markdown: How to Track To-Dos in Plain Text
How to write Markdown task lists with [ ] and [x] checkboxes: the exact syntax, where they render as clickable checkboxes, common mistakes, and how to keep your to-dos portable.
Read - June 24, 2026
How to Write a Great README in Markdown
A practical guide to writing a README in Markdown: the sections to include, the headings and fenced code blocks to use, and how to keep links working.
Read - June 22, 2026
A Simple System for Managing Code Snippets You Actually Reuse
A simple, plain-text workflow for managing the code snippets you actually reuse: capture, name, tag, and store them so you can find any one fast.
Read - June 20, 2026
Writing in Markdown on iPad: A Practical Workflow
A practical workflow for writing Markdown on iPad: pick a plain-text editor, learn the core syntax, set up your keyboard and Split View, and keep every draft portable.
Read - June 18, 2026
How to Organize Notes with Files, Projects, and Tags
Organize notes in three layers: a file per note, projects for stable buckets, and tags for themes that cut across them. Here is how to set it up.
Read - June 16, 2026
Why Plain Text Notes Outlast Every App
Plain text notes future-proof your writing because they are just characters in a documented encoding, not a vendor's format. Here is why they last.
Read - June 14, 2026
Fenced Code Blocks and Syntax Highlighting in Markdown, Explained
Fenced code blocks wrap code in triple backticks so Markdown leaves it untouched, and a language name after the opening fence switches on syntax highlighting.
Read - June 12, 2026
How to Write Markdown Tables (Without Losing Your Mind)
Markdown tables are a header row, a delimiter row of hyphens, and data rows separated by pipes. Here's the GFM syntax, column alignment, and fixes for the usual snags.
Read - June 8, 2026
CommonMark vs GitHub Flavored Markdown: What the Differences Actually Mean
CommonMark is the standardized Markdown spec. GitHub Flavored Markdown adds tables, task lists, strikethrough, and autolinks on top. Here's what changes.
Read - June 7, 2026
Markdown Syntax: A Practical Cheat Sheet for Headings, Lists, Links, and Code
A practical Markdown cheat sheet covering headings, lists, links, and code blocks, with copy-ready examples and the CommonMark and GFM rules worth remembering.
Read