The Wayback Machine - https://web.archive.org/web/20240922055842/https://github.blog/changelog/label/markdown/

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

Fenced block syntax for mathematical expressions

Users can now delineate mathematical expressions using ```math fenced code block syntax in addition to the already supported delimiters. Two dollar sign $$ delimiters are not required if this method is used.

**Here is some math!**

```math
\sqrt{3}
```

becomes

math-expression-as-a-fenced-code-block

Read more about working with advanced formatting

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

Reference labels in Markdown

When a URL in Markdown references a label, the label is now automatically rendered.

Shows the process of pasting the url of a label into an editor that renders the label when switching to the Preview tab

See more

Paste links directly in Markdown

HTML links that you paste in Markdown are now automatically converted into Markdown links. To paste HTML links as plain text, use cmd/ctrl + shift + v instead.

Pasting HTML links to Markdown

See more

Editor support for right-to-left languages

Right-to-left languages are now supported natively in text editors for Markdown files, comments, and gists.

Do you think they could be even better? Let us know how we can improve by contributing to our discussion.

Editor support for right to left languages

See more

Allow to upload .svg files to Markdown

It is now possible to upload .svg files to comments in issues, PRs, discussions, and Markdown files, like READMEs. You just have to drag and drop the file in the text area.

An animation showing how to upload a SVG image to an issue comment.

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
View more changes