Skip to content

markdown

Subscribe to all “markdown” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

→ ~ cd github-changelog
→ ~/github-changelog|main git log main
showing all changes successfully

New Markdown extension: Alerts provide distinctive styling for significant content

A screenshot of the five available types of Markdown alerts

Alerts are a Markdown extension displayed with distinctive colors and icons to indicate the significance of the content. Five different types of alerts are supported:

  • 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.

Learn more about how to use them within your Markdown content in the documentation.

See more

New delimiter syntax for inline mathematical expressions

We are introducing a new method for incorporating LaTeX-based mathematical expressions inline within Markdown. In addition to the existing delimiters, we now support delimiting LaTeX-style math syntax with dollar signs and backticks (for example, $`\sqrt{3}`$). This new syntax is especially useful if the mathematical expressions you're writing contain characters that overlap with Markdown syntax.

To learn more about using mathematical expressions within Markdown on GitHub, check out "Writing mathematical expressions" in the GitHub Docs.

See more

Specify theme context for images in Markdown GA

You can now specify whether to display images for light or dark themes in Markdown, using the HTML <picture> element in combination with the prefers-color-scheme media feature.

For example:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <img alt="Shows an illustrated sun in light color mode and a moon with stars in dark color mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>
See more

Wikis now support math and Mermaid diagrams

Earlier this year, GitHub added support for LaTeX style mathematical expressions and Mermaid diagrams in Markdown. However, until now, GitHub wikis were missing this support. You can now use these formatting features in GitHub wikis.

For more information about using mathematical expressions and Mermaid with GitHub, see creating diagrams and writing mathematical expressions in the GitHub documentation.

See more

Updates to Markdown pasting on GitHub

We've made some updates to how paste formatting works in Markdown-enabled fields on GitHub. For example, in code editors and on gists, you'll now be able to paste URLs on selected texts that will render as Markdown links like [...](https://...) by using the keyboard shortcut cmd|ctrl + v.

The following paste formatting changes have been made to pull requests, issue comments and wikis:

  • Spreadsheet cells and HTML tables will render as Markdown tables
  • Any copied text containing links will render the links in Markdown

All of this formatting can be disabled when pasting using the keyboard shortcut: cmd|ctl + shift + v or cmd|ctl + shift + Alt + v.

markdown formatting demo gif

Learn more about writing and formatting at GitHub.

See more

Render mathematical expressions in Markdown

You can now use LaTeX style syntax to render math expressions within Markdown inline (using $ delimiters) or in blocks (using $$ delimiters).

Writing expressions as blocks

To add math as a multiline block displayed separately from surrounding text, start a new line and delimit the expression with two dollar symbols $$.

**The Cauchy-Schwarz Inequality**
$$\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)$$

Displayed math markdown rendering

Writing inline expressions

To include a math expression inline with your text, delimit the expression with a dollar symbol $.

This sentence uses `$` delimiters to show math inline:  $\sqrt{3x-1}+(1+x)^2$

Inline math markdown rendering

GitHub's math rendering capability uses MathJax; an open source, JavaScript-based display engine. MathJax supports a wide range of LaTeX macros and a number of useful accessibility extensions. For more information, see the MathJax documentation and the MathJax Accessibility Extensions documentation.

Some users have previously used a workaround to generate images of mathematical expressions through API requests. Images generated this way will remain viewable, but this technique will no longer work. Going forward, expressions should be written directly in Markdown using LaTeX syntax as described above.

For more information about authoring content with advanced formatting, see Working with advanced formatting in the GitHub documentation.

See more

Specify theme context for images in Markdown (Beta)

You can now specify whether to display images for light or dark themes in Markdown, using the HTML <picture> element in combination with the prefers-color-scheme media feature.

For example:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <img alt="Shows an illustrated sun in light color mode and a moon with stars in dark color mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

An animated screenshot of an issue comment that changes the color mode. The content shows an octobiwan in light and stormtroopocat in dark color mode.

See more

Mermaid, topoJSON, geoJSON, and ASCII STL Diagrams Are Now Supported in Markdown and as Files

In addition to mermaid diagrams, we now allow users to render maps directly in markdown using fenced code blocks with the geojson or topojson syntax, and embed STL 3D renders using stl syntax.

Additionally, these diagrams are supported as files using their own extensions:

content type supported extensions
mermaid .mermaid, .mmd
geoJSON .geojson, .json
topoJSON .topojson, .json
STL .stl

image

For more information about using diagrams on GitHub, see Creating diagrams in the GitHub documentation

For more information about non-code filetypes on GitHub, see Working with non-code files

geoJSON

### Here's a geoJSON map in markdown

```geojson
{
  "type": "Polygon",
  "coordinates": [
      [
          [-90,30],
          [-90,35],
          [-90,35],
          [-85,35],
          [-85,30]
      ]
  ]
}
```

image

topoJSON

### Here's a topoJSON map in markdown

```topojson
 {"type":"Topology","transform":{"scale":[0.003589294092944858,0.0005371535195261037],"translate":[-179.1473400003406,17.67439566600018]},"objects":{"counties":   {"type":"GeometryCollection","geometries":[{"type":"MultiPolygon","arcs":[[[0,1,2,3]]],"id":53073},{"type":"Polygon","arcs":[[4,5,6,7,8,9]],"id":30105},{"type":"Polygon","arcs": [[10,11,12,1
 ...
```

image

STL

### Here's an STL 3D render in markdown

```stl
solid cube_corner
  facet normal 0.0 -1.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
  ...
```

image

See more

Specify theme context for images in Markdown

Users can now specify the theme an image is displayed for in Markdown. Appending #gh-dark-mode-only or #gh-light-mode-only to the end of an image url will define whether it's only shown to viewers using a light or a dark GitHub theme. For example:

Two screenshots of the same issue in dark and light color mode demonstrating the two fragment options by showing an optimized github logo for each color mode

The GitHub logo in the above screenshots uses the following Markdown to specify the theme context:

![GitHub-Mark-Light](https://user-images.githubusercontent.com/3369400/139447912-e0f43f33-6d9f-45f8-be46-2df5bbc91289.png#gh-dark-mode-only)![GitHub-Mark-Dark](https://user-images.githubusercontent.com/3369400/139448065-39a229ba-4b06-434b-bc67-616e2ed80c8f.png#gh-light-mode-only)
See more

Preview the Markdown rendering of gists

You can now preview renderings of Markdown files that you edit in GitHub Gist.

It has long been possible to preview the Markdown rendering of file edits or comments on GitHub. But these Markdown previews weren't available for gist files. Now, when creating or editing a gist file with the Markdown (.md) file extension, a Preview or Preview changes tab will display a Markdown rendering of the file contents. This lets you easily switch between the source view and Markdown view of the file.

image

For more information about gists, visit Editing and sharing content with gists. Get started by creating a secret gist, or a public gist for sharing, at gist.github.com.

See more

Keyboard shortcuts for quotes and lists

We've added keyboard shortcuts for quotes and lists in Markdown files, issues, PRs and comments.

To add quotes, use cmd+shift+. on Mac or ctrl+shift+. on Windows/Linux.
To add an ordered list, use cmd+shift+7 on Mac or ctrl+shift+7 on Windows/Linux.
To add an unordered list, use cmd+shift+8 on Mac or ctrl+shift+8 on Windows/Linux.

Keyboard shortcuts

For a full list of all our keyboard shortcuts, see our docs.

See more

Fixed-width font support in Markdown-enabled fields

You can now choose to use a fixed-width font in Markdown-enabled fields, like issue comments and pull request descriptions. Currently these fields use a variable-width font, which can make it difficult to edit advanced Markdown structures like tables and code snippets.

To enable, go to your appearance settings and toggle on Use a fixed-width (monospace) font when editing Markdown in the “Markdown editor font preference” section.

fixed-width-font

Learn more about writing and formatting on GitHub.

See more
View more changes