Adobe Markdown Authoring Extension for Visual Studio Code
This is a Visual Studio Code extension that enhances the built-in Markdown preview feaures with Adobe extensions to the Markdown specification.
This is a significant rewrite of the Adobe Experience League Markdown Authoring extension. This version is fully compatible with version 1.x of the extension. This version no longer has a dependency on the markdown-it-adobe-plugin module. The markdown-it-adobe-plugin module is deprecated and will no longer be maintained.
See CHANGELOG.md for details.
See docs/PLUGIN.md for details on the markdown-it-adobe-plugin.
See docs/DEPLOY.md for details on how to deploy the extension.
See docs/RULES.md for details on the custom markdownlint rules.
Currently this plugin extends the CommonMark specification, which is slightly different from the Git-flavored Markdown described in the Adobe Contributor Guide.
Features
In addition to the standard markdown preview features provided by VS Code that adhere to the CommonMark specification, this extension attempts to provide a high-fidelity representation of Markdown that adheres to the custom Markdown syntax specified in the Adobe Markdown Syntax Style Guide.
Supported Markdown extensions
- Note, Caution, Important, Tip, Warning, Admin, Availability, Prerequisites
- Embedded video
- More Like This
- Various UI tags for localization
- Snippets and Includes
- Shadeboxes
Installation
The easiest way to install the Adobe Visual Studio Code Markdown Extensions is from the Visual Studio Code extension marketplace.
- Install Visual Studio Code 1.44.0 or higher
- Launch Code
- From the command palette Ctrl-Shift-P (Windows, Linux) or Cmd-Shift-P (OSX)
- Select Install Extension
- Choose the extension
- Reload Visual Studio Code
Examples
Here are some examples of the Adobe extensions in action. If you have the extension installed, it will format this document in the built-in VSCode preview panel. If you do not have the extension installed, the generic VSCode Markdown Preview will use the CommonMark spec to render the alert extensions as block quotes.
Note
> [!NOTE]
>
> Here is a note component. Notice that it is just a blockquote that has a [!NOTE] label at the beginning of the code.
[!NOTE]
Here is a note component. Notice that it is just a blockquote that has a [!NOTE] label at the beginning of the code.
Caution
> [!CAUTION]
>
> Here is a caution component. Notice that it is just a blockquote and that you can _embed_ inline markdown including `pre-formatted text` and other **chicanery**
[!CAUTION]
Here is a caution component. Notice that it is just a blockquote and that you can embed inline markdown including pre-formatted text and other chicanery
[!TIP]
Here is a tip [!TIP] This is after this.
Important
> [!IMPORTANT]
>
> Here is the _IMPORTANT_ component. It's only one line.
[!IMPORTANT]
Here is the IMPORTANT component. It's only one line.
Tip
> [!TIP]
>
> Here is the _TIP_ component. It's only one line.
Shade Boxes
Shade boxes are useful for setting off a section of content from the rest of the page. For example, the Workfront team likes to add "Example" boxes that contains text, images, and code samples to achieve a specific purpose. A shade box might also be useful for "On Your Own" or "Use Case" sections, or for extended notes or tips.
To create a shade box, add >[!BEGINSHADEBOX] at the beginning of the section and >[!ENDSHADEBOX] at the end. All content between these begin and end tags will have a gray background. Adding a label to BEGINSHADEBOX (such as >[!BEGINSHADEBOX "Use Case] is an optional way to create a bolded shade box title. You can also just add bold text or a heading on the next line.
Example:
[!BEGINSHADEBOX "Removing the border in an HTML Table"]
In some cases, you use an HTML table to create a balanced design, but you don't want the content to look like a table. To turn off a border for a one-row HTML table, use this syntax:
<table>
<tr style="border: 0;"></tr>
</table>
[!NOTE]
Don't overuse. For normal tables, we want to keep a consistent design across
content.
In a three-column table, you can also add
and | to distribute the cell content evenly across the view area. If it were not so, I would have told you.
This is the last line of the shade box.
[!ENDSHADEBOX]
Video
!VIDEO
Exposed Commands
| Name |
Description |
Default key binding |
| md-shortcut.showCommandPalette |
Display all commands |
ctrl+M ctrl+M |
| md-shortcut.toggleBold |
Make **bold** |
ctrl+B |
| md-shortcut.toggleItalic |
Make _italic_ |
ctrl+I |
| md-shortcut.toggleStrikethrough |
Make ~~strikethrough~~ |
|
| md-shortcut.toggleLink |
Make [a hyperlink](<www.example.org>) |
ctrl+L |
| md-shortcut.toggleImage |
Make an image  |
ctrl+shift+L |
| md-shortcut.toggleCodeBlock |
Make ```a code block``` |
ctrl+M ctrl+C |
| md-shortcut.toggleInlineCode |
Make `inline code` |
ctrl+M ctrl+I |
| md-shortcut.toggleBullets |
Make * bullet point |
ctrl+M ctrl+B |
| md-shortcut.toggleNumbers |
Make 1. numbered list |
ctrl+M ctrl+1 |
| md-shortcut.toggleCheckboxes |
Make - [ ] check list (Github flavored markdown) |
ctrl+M ctrl+X |
| md-shortcut.toggleTitleH1 |
Toggle # H1 title |
|
| md-shortcut.toggleTitleH2 |
Toggle ## H2 title |
|
| md-shortcut.toggleTitleH3 |
Toggle ### H3 title |
|
| md-shortcut.toggleTitleH4 |
Toggle #### H4 title |
|
| md-shortcut.toggleTitleH5 |
Toggle ##### H5 title |
|
| md-shortcut.toggleTitleH6 |
Toggle ###### H6 title |
|
| md-shortcut.addTable |
Add Tabular values |
|
| md-shortcut.addTableWithHeader |
Add Tabular values with header |
|
| md-shortcut.toggleNote |
Make a [!NOTE] block |
ctrl+m ctrl+n |
| md-shortcut.toggleTip |
Make a [!TIP] block |
ctrl+m ctrl+t |
| md-shortcut.toggleCaution |
Make a [!CAUTION] block |
ctrl+m ctrl+c |
| md-shortcut.toggleImportant |
Make an [!IMPORTANT] block |
ctrl+m ctrl+p |
| md-shortcut.toggleWarning |
Make a [!WARNING] block |
ctrl+m ctrl+w |
| md-shortcut.toggleMoreLikeThis |
Make a [!MORELIKETHIS] block |
ctrl+m ctrl+m |
| md-shortcut.toggleVideo |
Make a [!VIDEO] block |
ctrl+m ctrl+v |
| md-shortcut.toggleDNL |
Make a [!DNL] block |
ctrl+m ctrl+d |
| md-shortcut.toggleUIControl |
Make a [!UICONTROL] block |
ctrl+m ctrl+u |
Markdown Lint Validation Settings
This package uses David Anson's Markdown-Lint package to validate the markdown. In addition to the built-in validation rules, this package adds support for Adobe Flavored Markdown.
Changing the Markdown-Lint Validation Settings
When it starts up for the first time the Adobe Markdown Authoring extension will look for existing settings in the VSCode Settings. If it does not find them, it will add the default settings below. If it does find them, it will default to the values found in the user settings.
To change the settings, go to Preferences > Settings > markdownlint.
markdownlint.config: {
"line-length": false,
"AM001": false,
"AM011": false,
"MD003": {
"style": "atx"
},
"MD004": {
"style": "dash"
},
"MD007": {
"indent": 4
},
"MD009": false,
"MD012": false,
"MD014": false,
"MD024": false,
"MD025": {
"front_matter_title": ""
},
"MD026": false,
"MD027": false,
"MD028": false,
"MD030": {
"ul_multi": 3,
"ol_multi": 2
},
"MD033": {
"allowed_elements": [
"a",
"b",
"br",
"caption",
"code",
"col",
"colgroup",
"div",
"em",
"I",
"img",
"li",
"ol",
"p",
"pre",
"s",
"span",
"strong",
"sub",
"sup",
"table",
"tbody",
"td",
"tfoot",
"th",
"thead",
"tr",
"u",
"ul"
]
},
"MD036": false,
"MD038": false,
"MD039": false,
"MD040": false,
"MD045": false
}
Custom Rules
In addition to the standard support MD### rules, Adobe Markdown Extension supports AM### rules, which are specific to
Adobe Flavored Markdown.
"markdownlint.customRules": [
"{AdobeExl.adobe-markdown-authoring}/dist/rules/index.bundle.js"
]
Extension Settings
Since this is an expansion on the built-in VS Code preview extension, any settings applicable to that extension also apply to this one. You can find more information about support for Markdown in Visual Studio Code at in the Visual Studio Code online documentation.
| | 
