…especially syntax highlighting. This change brings in `morphdom` to allow us to be more efficient about how we apply the changes needed when the Markdown source re-renders. Instead of replacing all the content with every single change, we apply only the selective edits needed to adapt our existing markup to the target markup. Once this process is done, we introduce one `TextEditor` instance for each `pre` tag in the markup, then persist those editor elements in the rendered output so that we don't have to spend so much time creating and destroying editors. This is a _huge_ performance win, especially in documents with lots of code blocks. The editor instances are cached using the `pre` elements as keys, which is now possible because the `pre` elements themselves are preserved across re-renders. Editors are created when new `pre` elements appear, and are destroyed when they are no longer needed, change their contents whenever the contents of the `pre` changes, and change language modes whenever the code fence language identifier changes. This approach is now used no matter which Markdown renderer is employed; we manage syntax highlighting ourselves in all cases rather than letting `atom.ui.markdown` do it. |
||
---|---|---|
.. | ||
assets | ||
keymaps | ||
lib | ||
menus | ||
scripts | ||
spec | ||
styles | ||
.gitignore | ||
package-lock.json | ||
package.json | ||
README.md |
Markdown Preview package
Show the rendered HTML markdown to the right of the current editor using ctrl-shift-m.
It is currently enabled for .markdown
, .md
, .mdown
, .mkd
, .mkdown
, .ron
, and .txt
files.
Customize
By default Markdown Preview uses the colors of the active syntax theme. Enable Use GitHub.com Style in the package settings to make it look closer to how markdown files get rendered on github.com.
When Use GitHub.com Style is selected, you can further customize the theme of the Markdown preview with the GitHub.com Style Mode setting. Since the GitHub website has a light theme and a dark theme, markdown-preview
allows you to choose which theme to use when previewing your files. By default, it will use whatever mode is preferred by your system, but you can opt into “Light” or “Dark” to force it to use a particular theme.
No matter which theme you use, you can apply further customizations in your styles.less
file. For example:
.markdown-preview pre {
background-color: #444;
}
Language identifiers in fenced code blocks
A detailed Markdown specification helps to ensure that Markdown is displayed consistently across multiple parsers. Sadly, the same isn’t true of code block language identifiers — the strings you use to tell the renderer what sort of code is inside a code block.
The CommonMark specification explicitly avoids standardizing these identifiers:
The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag. However, this spec does not mandate any particular treatment of the info string.
There are several valid ways to infer specific languages from language identifiers such as js
, less
, coffee
, and c
. This package supports the following systems, configured via the Syntax Highlighting Language Identifiers setting:
- Linguist: Used by GitHub (previously the default and only language identification system).
- Chroma: Used by CodeBerg/Gitea/Hugo/Goldmark.
- Rouge: Used by GitLab/Jekyll.
- HighlightJS: Used in a number of places, but most relevantly on the Pulsar Package Registry website.
If none of these systems meets your needs, you may specify custom language identifiers. This may not be as portable as the systems described above, but it will at least produce the desired outcome on your own system.
The setting Custom Syntax Highlighting Language Identifiers lets you define a list of custom language identifiers that match up to languages available within your Pulsar installation.
For example, if you wanted to map j
to JavaScript and p
to Python, you’d add the following text to the Custom Syntax Highlighting Language Identifiers field:
j: source.js, p: source.python
Now markdown-preview
will understand what to do with fenced code blocks that begin with ```j
or ```p
. These custom identifiers will work alongside whatever system you’ve chosen with Syntax Highlighting Language Identifiers, but will supersede that system in the event of conflict.