Markdown Guide

Writing basics

How Markdown turns plain text into structure

A Markdown file stores ordinary text plus a small set of punctuation markers. A parser reads those markers and creates headings, paragraphs, lists, links, code blocks, and other document elements. The source stays readable because the punctuation follows familiar writing conventions rather than hiding the content in tags or binary formatting.

The .md file contains the source. GitHub, an editor preview, a documentation system, or a Python library produces the rendered view. The same source can look different because each destination controls fonts, spacing, colors, and supported extensions. Markdown preserves structure; it does not promise identical visual design.

CommonMark provides a precise baseline for the syntax that caused the most disagreement among early Markdown implementations. GitHub Flavored Markdown builds on that baseline with features such as tables, strikethrough, task list items, and autolink extensions. Other apps add their own features. Use the smallest feature set that satisfies the destination.

Paragraphs and line breaks

A blank line separates paragraphs. A normal line wrap inside one paragraph may be displayed as a space, even if the source editor shows two lines. This lets writers wrap long source lines without changing the document structure.

For a deliberate line break inside a paragraph, end the first line with two spaces before the newline. CommonMark also supports a backslash before the newline, but trailing spaces are more widely recognized by writers. Chat composers often use Shift + Enter instead of Markdown line-break syntax.

Do not add repeated blank lines to create visual space. Renderers usually collapse them. If a document needs more separation, use a heading, thematic break, list, or quote so the source explains why the separation exists.

Headings that form a useful outline

ATX headings begin with one to six hash marks. The level expresses hierarchy, not desired font size. Use a single H1 for the page title in most standalone documents. Main topics become H2 sections; details inside a topic become H3 sections. Skipping from H2 to H5 makes the outline harder for readers and assistive technology to follow.

Keep heading text short and specific. A heading such as “Deploy the preview” gives more information than “Next steps.” On GitHub, headings also create linkable section anchors, so stable wording helps other documents keep working.

Emphasis, code, and literal punctuation

Use **bold** for strong importance and *italic* for ordinary emphasis. A triple marker can combine them, but a sentence with several combined styles is usually asking for clearer wording instead. Strikethrough with two tildes is a GitHub-style extension rather than CommonMark.

Inline code is not just another visual style. It signals literal input: a command, property, filename, function, or value. If the code itself contains a backtick, wrap it in a longer run of backticks. Backslash escaping serves a different purpose: it tells the parser that a punctuation character should remain visible, as in \*literal asterisks\*.

Document structure

Lists without broken indentation

Unordered list markers can be hyphens, asterisks, or plus signs. Pick one style within a document. Ordered lists use a number followed by a period or, in CommonMark, a closing parenthesis. Many renderers calculate the visible numbering, so authors often write 1. for every item to make rearranging easier. Use explicit numbers when the source itself must communicate the sequence.

A child list or paragraph must be indented far enough to belong to its parent item. The exact amount depends on the width of the marker and following spaces. If a deeply nested list is difficult to fix, that is often a writing problem rather than a punctuation problem. Convert some levels into headings or separate lists.

Task lists use - [ ] and - [x]. GitHub and Obsidian support them; CommonMark does not define them. In portable documents, write a status word such as “Pending” or “Done” when losing the checkbox would change the meaning.

Links, images, and code

Links and images that survive a move

An inline link combines visible text with a destination: [label](URL). A reference link moves the destination to a definition elsewhere in the file, which can make long documents easier to edit. Angle brackets create explicit autolinks for URLs and email addresses under CommonMark.

Relative links are useful inside repositories and documentation projects because they can move with the files. Their behavior depends on the file location and publishing system. Absolute HTTPS URLs are easier to move between unrelated tools, but they break if the external destination changes.

Image syntax adds an exclamation mark before a link. The square-bracket text becomes the image description when the renderer uses it as alt text. Write what the image communicates, not “image” or the filename. A local image path must be published with the Markdown file or it will render as a broken reference.

Block quotes and fenced code blocks

Start quoted lines with >. Block quotes can contain paragraphs and lists, but a quote that becomes deeply nested is difficult to read in source. GitHub alerts and Obsidian callouts extend a block quote with a typed marker; other renderers may show the same source as an ordinary quote.

Fenced code blocks begin and end with at least three backticks or tildes. Add a language name after the opening fence when the destination supports syntax highlighting. The language label is an information string in CommonMark; the specification does not require a particular highlighter or color scheme.

When documenting a fenced block inside another fenced block, make the outer fence longer than the inner one or use tildes outside and backticks inside. This prevents the first inner fence from closing the example too early.

Platform differences

What GitHub adds to Markdown

GitHub uses GitHub Flavored Markdown as its base and adds contextual features across repository files, issues, pull requests, and discussions. Pipe tables display row-and-column data. Task lists show checkboxes. Two tildes create strikethrough. GitHub also documents footnotes and alerts in supported writing surfaces.

Context still matters. A feature available in an issue comment may behave differently in a wiki or repository file. GitHub’s own documentation notes, for example, that footnotes are not supported in wikis. Mentions and issue references also depend on repository context; they are not portable Markdown links.

Raw HTML is filtered. That protects readers but means HTML copied from another environment may lose elements or attributes. Prefer Markdown syntax when GitHub provides it, and use the GitHub compatibility view before relying on an extension.

Markdown for notes and Obsidian

Obsidian stores notes as local Markdown files and supports both standard Markdown links and compact wikilinks. A wikilink such as [[Project plan]] is convenient inside a vault and can update when a note is renamed. A standard link such as [Project plan](Project%20plan.md) is more portable outside Obsidian.

Obsidian adds highlights, comments, footnotes, callouts, embeds, block references, and other note-oriented behavior. These features are useful when the vault is the permanent home of the content. If the same notes must also render on GitHub or a static site, decide which extensions are allowed and test an exported sample early.

Tables are useful, but not universal

Pipe tables are not part of CommonMark. They are widely associated with GitHub-style Markdown, and Obsidian supports them as well. A table needs a header row and separator row; each data row should have a consistent number of cells. Literal pipe characters inside cells must be escaped where the renderer requires it.

Tables become hard to read on narrow screens and in raw source when cells contain paragraphs or long code. Use a list when the relationship is simple. When a table is the right structure, create it with the Markdown Table Generator, then preview it in the final platform.

Reference links keep repeated destinations readable

Inline links work well when each destination appears once. A document with the same long URL in several places is often easier to edit with reference links. The sentence contains a short label, while the destination is defined elsewhere in the file.

Read the [release policy][policy] before publishing.

[policy]: https://example.com/docs/release-policy "Release policy"

The reference label is not normally shown to the reader. Labels are matched without regard to letter case, and extra internal whitespace is normalized by CommonMark. Put definitions near the paragraph for a short note or collect them at the end for a long document. Pick one convention and keep it consistent.

A missing definition leaves the source looking like bracketed text instead of a link. This can be easy to miss when definitions are far from their uses, so preview after renaming labels or moving sections between files.

Horizontal rules and other separators

Three or more asterisks, hyphens, or underscores on a line can create a thematic break. The marker means the topic has changed; it is not a command to add arbitrary vertical space. Surround it with blank lines, especially when using hyphens, because a line of hyphens directly below text can participate in Setext heading syntax.

Deployment finished.

---

Rollback notes begin here.

Setext headings use a line of equals signs or hyphens below heading text. They are part of CommonMark, but ATX headings with hash marks make the level clearer while editing and support all six levels. Most teams should choose one heading style rather than mixing both.

Escape punctuation only when the parser needs help

Markdown punctuation is ordinary text until it appears in a pattern the parser recognizes. Asterisks around a word create emphasis, but a single asterisk in a sentence may need no special handling. Add a backslash when punctuation would otherwise start formatting: \# not a heading, \*not italic\*, or 1\. not a list.

Backslashes do not escape every character. CommonMark defines the ASCII punctuation characters that may be escaped. Inside code spans and fenced code blocks, use code rules rather than adding backslashes throughout the content. Over-escaping makes the source noisy and can leave visible backslashes in parsers with different rules.

Raw HTML is powerful and less portable

CommonMark allows several forms of raw HTML, so authors sometimes use tags for details, keyboard input, custom alignment, or layouts Markdown cannot express. The destination decides whether those tags are preserved, escaped, or removed. GitHub filters unsafe HTML. Chat applications usually support only their own formatting syntax. Word and note importers may convert the tag into a native block or discard it.

Use HTML when the publishing system explicitly supports it and the document is unlikely to move. Otherwise, prefer an ordinary paragraph, list, table, or code block. Never assume that allowing Markdown also makes arbitrary HTML from an untrusted author safe; parsing and sanitizing are different operations.

Plan local files, links, and images as a set

A Markdown document rarely travels alone. Repository guides link to neighboring files, documentation pages use an image folder, and note systems create links between many documents. Before moving a folder, identify which paths are relative to the current file and which are resolved from a project root by the publishing system.

Spaces and letter case cause common failures. A link to Setup Guide.md may need URL encoding in one renderer, while another accepts the literal space. A link that works on a case-insensitive laptop can fail after deployment to a case-sensitive server. Match the filename exactly and prefer stable lowercase names when starting a new web documentation project.

For images, keep the original asset available, add useful alternative text, and avoid relying on a temporary clipboard or local application URL. Resize large images before publishing instead of using unsupported Markdown width syntax. If the destination requires image dimensions, follow that platform’s documented HTML or component syntax.

Troubleshooting and publishing

Debug Markdown from the block structure outward

When formatting breaks, inspect the source in a fixed order. First, check blank lines and indentation around paragraphs, lists, quotes, and code blocks. Next, check that fences and emphasis markers are balanced. Then confirm that link destinations and reference definitions are complete. Finally, verify that the feature belongs to the destination’s dialect.

Reduce a broken example to the smallest lines that still fail. If a table works alone but not inside a list, the problem is likely nesting or indentation. If it works on GitHub but not in CommonMark, it is probably an extension rather than a typing error. A small example is also easier to compare in two preview tools.

Review a Markdown document like source code

Plain text works well with version control because a diff can show the exact lines that changed. Keep paragraphs at a line-wrapping style the team agrees on; changing between hard-wrapped and unwrapped paragraphs can obscure the real edit. Avoid reformatting unrelated tables or lists in the same change.

Automated formatters can normalize tables, list markers, or wrapping, but they may also create large diffs. Run them consistently or only on the section being edited. A linter is useful when it enforces decisions the destination needs—such as one H1, ordered heading levels, or nonempty link text—not simply because it has many rules.

Review the rendered page and the source. The rendered page catches missing structure and broken assets. The source review catches hard-to-maintain indentation, opaque link labels, and platform extensions that another renderer may not understand.

Choose an editor by workflow, not by feature count

A plain-text editor is enough for short documents and version-controlled repositories. A preview is useful when the destination has unfamiliar extensions. Link completion helps in a connected note system. File trees, search, Git integration, and export commands matter only when the project needs them.

Keep the source in UTF-8 and use the .md or .markdown extension. Give files stable, descriptive names. Relative image and document paths should use forward slashes when the publishing workflow expects web-style paths. Before a migration, test one representative file containing headings, lists, links, images, code, and a table.

If the next destination is a visual editor rather than a Markdown renderer, convert the structure before pasting. MarkdownKit’s Markdown to Rich Text workflow prepares formatted clipboard content. Use Markdown to HTML when the destination needs source markup.

A final portability checklist

• Choose the renderer before choosing extensions.
• Keep heading levels logical rather than styling by size.
• Use blank lines to separate blocks.
• Keep list indentation consistent and nesting shallow.
• Write descriptive link labels and image alt text.
• Prefer fenced code blocks for multi-line code.
• Treat tables, task lists, footnotes, alerts, wikilinks, and spoilers as extensions.
• Preview the document in the same platform where readers will use it.