Markdown Everywhere

Embed and highlight and preview markdown in any language which support line-comment or block-comment for vscode. Also used for interpreting text as markdown.

e.g. Quickly preview LaTeX/ Highlight python markdown cell/ Highlight julia markdown doc string

Embed & Highlight

preview

Preview

Five mode

• splitter: ignore source code part and put <hr> as splitter
• ignored: ignore source code part
• fenced: keep source code as fenced code
• folded: keep source code as folded fenced code
• raw: do nothing (for working with preview-inject)

splitter Help organize information
ignored
fenced
folded
raw

change it at settings.json - preview-mode

using preview-mode-language could setting for respective languages

provide setting to open preview automatically for listed languages

Preview Inject

Do some actions in parsing, only support to do some replacing before parse markdown to html now. (config by changing settings.json)

Quickly LaTeX previewing

    "markdown-everywhere.preview-mode-language": {"latex":"raw"},
    "markdown-everywhere.preview-mode-inject": [
        {"language":"latex","path":".*","beforeSource":" let {src,options}=args\n const lines = src.split(/\\r?\\n|\\r\\n?/);\n let lino = -1;\n let currentOffset = 0;\n \n while (++lino < lines.length) {\n let pa=null;\n let line = lines[lino];\n\n // MD remove `\\label`, do not change number of lines, directly replace\n line=line.replace(/\\\\label{.*?}/g,'')\n\n // MD fix equation, add 3 more lines. fix offset for trace\n pa=/\\\\begin{(equation|display|alignat|aligned|align|multline|flalign)}/\n if (pa.exec(line)){\n line=line.replace(pa,(m)=>'\\n\\n$$\\n'+m)\n currentOffset+=3\n options.offset.push([lino + currentOffset, currentOffset])\n }\n\n // MD fix equation\n pa=/\\\\end{(equation|display|alignat|aligned|align|multline|flalign)}/\n if (pa.exec(line)){\n line=line.replace(pa,(m)=>m+'\\n$$\\n\\n')\n currentOffset+=3\n options.offset.push([lino + currentOffset, currentOffset])\n }\n\n lines[lino] = line;\n }\n return lines.join('\\r\\n');\n \n "}
    ],

Documenter.jl style LaTeX-math-fencing

    "markdown-everywhere.preview-mode-inject": [
        {"language":"julia","path":".*","beforeSource":" return args.src.replace(/```math/g,'$$$$\\n').replace(/```/g,'\\n$$$$').replace(/``/g,'$').replace(/\\\\\\\\/g,'\\\\') "}
    ],

The JSON generated from issue. More applications may be listed in the issue.

Extract Markdown

Command "Extract as Markdown to Clipboard" (also in right-mouse-click context menu.)

Convert selection into Markdown format according to the rules and preview mode, place it into the clipboard.

Can be used to copy Markdown from formats similar to JSDoc, automatically ignoring the * at the beginning of each line.

Enhancing-typing

whileSymbol or whileRegExp (if whileSymbol undefined) will be used for enhancing typing.
There will be some onEnterRules pushed to markdown.
So it will also affect the editing of normal markdown files.
You can turn off it in "settings.json".

onEnterRules checks the previous line, so it does not work on the first line of a markdown region.

Example:

// MD the first line
// MD the second line

After pressing enter at "e", it will automatically append "// MD ".

// MD the first line
// MD the second line
// MD 

change it at "settings.json"

Recommended Color

You can put those into "settings.json" to adjust the color.
So that markdown can be easily distinguished from both code and comments.

"editor.tokenColorCustomizations": {
    "[Default Dark+]": {
        "textMateRules": [
            {
                "scope": "meta.embedded.block.everywhere.md markup.heading, meta.embedded.block.everywhere.md markup.bold",
                "settings": {
                    "foreground": "#61aa71",
                }
            },
            {
                "scope": "meta.embedded.block.everywhere.md punctuation.definition.list.begin.markdown, meta.embedded.block.everywhere.md entity.name.tag",
                "settings": {
                    "foreground": "#599aa5",
                }
            },
            {
                "scope": "meta.embedded.block.everywhere.md entity.other.attribute-name",
                "settings": {
                    "foreground": "#98bdc4",
                }
            },
            {
                "scope": "meta.embedded.block.everywhere.md markup.inline.raw, meta.embedded.block.everywhere.md string",
                "settings": {
                    "foreground": "#ceca8b",
                }
            },
            {
                "scope": "meta.embedded.block.everywhere.md, meta.embedded.block.everywhere.md meta.embedded",
                "settings": {
                    "foreground": "#9abb87",
                }
            }
        ]
    }
}

Supported List

(note that some languages require that you install an VS Code extension that provides a grammar for that language)

Customize

Imitate rules and add new rules to "settings.json". And then run command "Build Markdown Embedding Rules" and then reload (press "F1", type "Build Markdown Embedding Rules" and "Reload Window"). And you need to run build command again when you update this extension.

Save the first element defaultRules to keep default rules. Remove to only use customized rules. Example:

"markdown-everywhere.customized-rules": [
    "defaultRules",
    {
        "name": "number-sign-equals",
        "beginRegExp": "#=\\s*\\[markdown\\]",
        "endRegExp": "=#",
        "example": "#= [markdown]<br># title<br>content<br>=#",
        "languages": [
            { "name": "julia", "source": "source.julia" }
        ]
    }
]

Rules

There are 4 types of rules, corresponding to 4 implementations

LRSW
line rule starts with the mark
whileRegExp

// MD connecting line-comment
// MD each line starts with the mark

rule={
    name: "double-slash-MD",
    whileRegExp: "// MD",
    example: "// MD # title<br>// MD content<br>",
    languages: [
        ...languages.filter(l => l.comments.lineComment === "//"),
        { name: "antlr", source: "source.antlr" },
        { name: "qasm-lang", source: "source.qasm" },
    ]
}

BR
block rule
beginRegExp+endRegExp

May introduce incorrect rendering, for example, use """ as markdown content in the follow demo

""" [markdown]
block comment starts with a start mark
and finally a end mark
"""

rule={
    name: "triple-quote",
    beginRegExp: "\"\"\"\\s*\\[markdown\\]",
    endRegExp: "\"\"\"",
    example: "\"\"\" [markdown]<br># title<br>content<br>\"\"\"",
    languages: [
        ...languages.filter(l => JSON.stringify(l.comments.blockComment||"") === JSON.stringify(["\"\"\"", "\"\"\""])),
    ]
}

preview will break in a situation like this, the current preview does not parse the statements

a="""
asd
"""

you can custom rules without defaultRules to close the triple-quote rule

MR
mixed rule
beginRegExp+whileRegExp+endRegExp

May introduce incorrect rendering, for example, use */ as markdown content in the follow demo

/* [markdown]
 * block comment starts with a start mark
 * and each line starts with the mark
 * and finally a end mark
 */

rule={
    name: "slash-star",
    beginRegExp: "/\\*\\s*\\[markdown\\]",
    whileRegExp: "\\*(?!/)",
    whileSymbol: "*",
    endRegExp: "\\*/",
    example: "/* [markdown]<br>&nbsp;* # title<br>&nbsp;* content<br>&nbsp;*/<br>",
    languages: [
        ...languages.filter(l => JSON.stringify(l.comments.blockComment||"") === JSON.stringify(["/*","*/"])),
        { name: "antlr", source: "source.antlr" },
    ]
}

LRSM
line rule with a start mark
beginRegExp+whileRegExp

// [markdown]
// some connecting normal line-comment 
// starts with a start mark (which is normaly a line-comment)

rule={
    name: "double-slash",
    beginRegExp: "//\\s*\\[markdown\\]",
    whileRegExp: "//",
    example: "// [markdown]<br>// # title<br>// content<br>",
    languages: [
        ...languages.filter(l => l.comments.lineComment === "//"),
        { name: "antlr", source: "source.antlr" },
        { name: "qasm-lang", source: "source.qasm" },
    ]
}

There is bug for this case. Some languages such as LaTeX and MATLAB, LSMR rules not work. Have to inject into comment. It will introduce side effects: 1.The LRSM rules are also highlighted in block comment. 2.The following first line will be highlighted as comment. I haven't figured out the mechanism yet. So please put a empty line after these for the listed languages.
Add "injectToComment": true, in rule to active:

    {
        "name": "percentage",
        "beginRegExp": "%\\s*\\[markdown\\]",
        "whileRegExp": "%",
        "injectToComment": true,
        "example": "% [markdown]<br>% # title<br>% content<br>",
        "languages": [
            {"name":"matlab","source":"source.matlab"},
            {"name":"bibtex","source":"text.bibtex"},
            {"name":"tex","source":"text.tex"},
            {"name":"latex","source":"text.latex"}
        ]
    },

Extending from my pr in vscode-python (issue/pr).