Paste your README, or load one from any public repository, and check tables, alerts, task lists, footnotes, Mermaid, and math before you push. Below the editor: a complete GitHub Markdown reference.
Paste owner/repo, a repo URL, or a link to any .md file on GitHub
Every formatting feature GitHub supports in READMEs, issues, and pull requests — with the Markdown, the rendered result, and notes on where it works. Click Try in editor to load any example into the previewer above. Syntax follows GitHub’s official documentation. For syntax shared by every Markdown flavor, see the universal Markdown cheat sheet on MDConverter.
One to six # characters, then a space. GitHub builds an "Outline" menu from them and gives each one a link anchor.
# A first-level heading ## A second-level heading ### A third-level heading
A first-level heading
A second-level heading
A third-level heading
Wrap text in ** or __ for bold, * or _ for italic, and ~~ for strikethrough. Styles can be nested.
**This is bold text** _This text is italicized_ ~~This was mistaken text~~ **This text is _extremely_ important** ***All this text is important***
This is bold text
This text is italicized
This was mistaken text
This text is extremely important
All this text is important
GitHub has no Markdown syntax for these, but supports the HTML tags.
H<sub>2</sub>O and x<sup>2</sup> This is an <ins>underlined</ins> word.
H2O and x2
This is an underlined word.
Start a line with > to quote it. Quotes can contain other Markdown, including lists and code.
Text that is not a quote > Text that is a quote > > > A nested quote
Text that is not a quote
Text that is a quote
A nested quote
Single backticks for inline code; triple backticks (or ~~~) for a block. Add a language name for syntax highlighting.
Use `git status` to list changed files.
```python
def greet(name):
return f"Hello, {name}!"
```Use git status to list changed files.
def greet(name):
return f"Hello, {name}!"Write [text](URL). Plain URLs are linked automatically. Link to a heading with #anchor, or to another file with a relative path.
Visit [GitHub Pages](https://pages.github.com/). Autolink: https://github.com Jump to [the tables section](#tables). See the [contributing guide](docs/CONTRIBUTING.md).
Visit GitHub Pages.
Autolink: https://github.com
Jump to the tables section.
See the contributing guide.
Like a link with a leading !. Use relative paths for images in your repository. The <img> tag lets you set a width.
 <img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="48" alt="Small logo">
Start lines with -, *, or + for bullets, or numbers for an ordered list. Indent nested items to the parent's text.
- George Washington - John Adams 1. James Madison 2. James Monroe - Nested under item 2
A list item starting with [ ] or [x]. In issues and pull requests the checkboxes are clickable and track progress.
- [x] Write the press release - [ ] Update the website - [ ] \(Optional) Contact the media
Pipes separate columns; a row of hyphens under the header is required. Colons set alignment.
| Left-aligned | Center-aligned | Right-aligned | | :--- | :---: | ---: | | git status | git status | git status | | `git diff` | **bold** | \| pipe |
| Left-aligned | Center-aligned | Right-aligned |
|---|---|---|
| git status | git status | git status |
git diff |
bold | | pipe |
A blockquote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], or [!CAUTION]. GitHub shows each with its own color and icon.
> [!NOTE] > Useful information that users should know, even when skimming content. > [!TIP] > Helpful advice for doing things better or more easily. > [!IMPORTANT] > Key information users need to know to achieve their goal. > [!WARNING] > Urgent info that needs immediate user attention to avoid problems. > [!CAUTION] > Advises about risks or negative outcomes of certain actions.
Useful information that users should know, even when skimming content.
Helpful advice for doing things better or more easily.
Key information users need to know to achieve their goal.
Urgent info that needs immediate user attention to avoid problems.
Advises about risks or negative outcomes of certain actions.
Hide long content behind a clickable summary. Leave a blank line after </summary> so the Markdown inside renders.
<details> <summary>Click to see the build log</summary> ```bash npm run build ✓ Compiled successfully ``` </details>
npm run build
✓ Compiled successfullyAdd [^label] where the note applies and [^label]: text anywhere in the file. GitHub numbers them and moves them to the bottom.
Here is a simple footnote[^1]. A footnote can also have multiple lines[^2]. [^1]: My reference. [^2]: To add line breaks within a footnote, add 2 spaces to the end of a line. This is a second line.
A fenced code block with the language mermaid becomes a diagram: flowcharts, sequence diagrams, Gantt charts, and more.
```mermaid
flowchart LR
A[Push] --> B{Tests pass?}
B -->|Yes| C[Deploy]
B -->|No| D[Fix]
```Diagrams are drawn in the browser — click "Try in editor" to see this one rendered.
Inline math between $...$ or $`...`$; display math between $$...$$ or in a ```math block. GitHub renders it with MathJax.
Inline: $\sqrt{3x-1}+(1+x)^2$
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```math
E = mc^2
```Inline:
In .md files, a single newline is a space. End a line with a backslash, two spaces, or <br> to break it; leave a blank line for a new paragraph.
This example\ Will span two lines This is a new paragraph.
This example
Will span two lines
This is a new paragraph.
A backslash shows a Markdown character literally. HTML comments are hidden from the rendered page. Three hyphens make a rule.
Let's rename \*our-new-project\* to \*our-old-project\*. <!-- This comment will not appear in the rendered Markdown --> --- Text after the rule.
Let's rename *our-new-project* to *our-old-project*.
Text after the rule.
GitHub-specific shortcuts that only work on github.com: @mentions, #123 issue references, :emoji: shortcodes, and color chips for hex/rgb/hsl values in backticks (issues, PRs, and discussions only).
@octocat :+1: This PR looks great — it fixes #42. The background color is `#0969DA`.
Rendered only on github.com.
Start from a proven structure: copy a template or load it into the editor and fill it in.
Complete production template with Shields.io badges, architecture overview, installation, quickstart, API documentation, and contributing guidelines.
Close enough to catch nearly every formatting mistake, but not byte-for-byte — GitHub’s renderer isn’t available outside GitHub. Here’s exactly what matches and what differs.
README looks fine here but broken on GitHub? Work through 16 reasons GitHub Markdown doesn’t render — each with a tested fix.
Your text is rendered in your browser and never uploaded. Fetched READMEs come straight from GitHub to your browser.
Your README is saved in this browser as you type. Press Ctrl+S to download it as README.md.
Paste owner/repo, a repository URL, or a link to a specific .md file. Relative image links are fixed automatically.
All tools are free, run in your browser, and require no account.
Edit Markdown with a real-time preview, Mermaid, KaTeX math, drag-and-drop files, and one-click export.
13 diagram types with examples, live rendering, and SVG/PNG download.
Typeset equations as you type, with a copy-ready KaTeX cheat sheet of 180+ commands.
Pick sections, fill in your project, and download a GitHub-ready README.md with badges and a TOC.
Paste ChatGPT, Claude, or Gemini output and read it formatted, with tables, code, and math.
A plain-English introduction: what Markdown and .md files are, where it came from, and where it is used.
Preview .md files in Drive, edit in Docs' Markdown mode, and paste, convert, or export Markdown.
Six free tools tested with the same document: rendering, privacy, and phone support compared.
16 causes found by symptom — tables, lists, image paths, code fences, alerts, Mermaid, math — with tested fixes.
Preview shortcuts, settings verified on VS Code 1.141, built-in Mermaid and math, extensions, and fixes.
Open and read Markdown files formatted on Windows, Mac, Linux, iPhone, Android, Word, and Google Docs.
Exact preview shortcuts for Visual Studio, JetBrains, Zed, Xcode, Sublime, Neovim, Obsidian, and more.
Six free ways to read .md files in Chrome, Edge, Firefox, or Safari — compared for privacy and features.