Best practices for Markdown authoring in VSC

This page helps you create a consistent, parallel, readable browsing experience. You achieve this by doing the small things consistently right, from the ground up. (If you’re looking for editorial standards and style guidelines, see Editorial guidelines.)

Tips and rules to prevent common errors common-errors

File and folder names

Articles

TOC

Headings

Headings can be used to jump to a specific section of an article. You have the option of adding a specific heading anchor. (For editorial guidance, see Headings.)

Heading without anchor: ## Creating widgets

Heading with custom anchor: ## Creating widgets {#widgets}

In the first example, an anchor is generated automatically with the heading text hyphenated and made lowercase (creating-widgets).

For editorial guidance, see Headings.

Visual Studio Code tips vsc-tips

If you’re using Visual Studio Code (VSC) for editing, here are some tips and techniques that we’ve found useful.

Adobe Markdown Authoring extension for VSC adobe-extension

The Adobe Markdown Authoring extension is available for download in the VSC Extensions Marketplace.

This extension pack includes the following add-ons:

Known bugs and limitations

To view or report issues, see Issues.

Visual Studio Code add-ons we like vsc-addons

Feel free to add any extension to this list that you find useful.

Use Quick Open

Command+P is your friend. If you need to open a file, press Command+P and paste or start typing the filename, or open one of your recently edited files. Press Command+Shift+P to open the Command palette.

Linking tips linking-tips

See the Linking tips article.

Global Find/Replace global-find-replace

Visual Studio Code lets you find/change text either within a document or across all the files you have open.

When you use the Replace in Files feature, replacing items automatically saves the affected files.

Wildcard find/replace wildcards

If you do a lot of finding and changing, or if you’re making global changes for a migration or cutover, using wildcards can save time. But this section isn’t for everyone.

Common expressions

Wildcard search examples

Here are some useful strings for converting the loc tags in HTML table content.

search/replace docs.adobe.com links

https://docs.adobe.com/content/help/en/(.+?)$
https://experienceleague.adobe.com/docs/$1

search/replace links

<a href="(.+?)"(.+?)> (.+?)</a>
[$3]($1)

In the above example, we use three wildcard groups. The first group captures the link path. The second group captures HTML properties that we don’t need. The third group captures the link text. We then put the link text in brackets [$3] and the link path in parentheses ($1).

search replace image

<img (.+?)src="assets/(.+?)"(.+?)>
![$2 image](assets/$2)

You might need to tweak the above example by adding or removing spaces, depending on how the table was migrated.

search replace code

<span class="codeph">(.+?)</span>
`$1` (Markdown) or <code>$1</code> (HTML)

You might need to add a space before or after the wildcard group, depending on how the table was migrated.

search replace varname

<span class="varname">(.+?)</span>
*$1* (Markdown) or <i>$1</i>

search for a character that’s not a specific character

<a [^h]

In the above example, we want to find HTML links that start with something other than a href.

\{[^#](.+?)\}

In the above example, we want to find anchor IDs that are missing the # character.

&search replace [ ] in headings

We’ll use [!DNL] as an example below.

\# (.+?) \[!DNL(.+?)]
# $1$2

Above, we use \ to escape characters such as # and [ used in expressions.

In the below example, we’ll look for anchors in a TOC that are missing the # character, such as {admin} instead of {#admin}:

\{[^#]

Copy empty alt text with image name

For example, you want ![](assets/rule-regs.png) to become ![rule-regs](assets/rule-regs.png). Here’s how:

!\[\]\(assets/(.+?)\.(.+?)\)
![$1](assets/$1.$2)

Find spaces or tabs at end of a line

[\s]+$

Find step numbers that start with 2-9 instead of 1.

Best practice is to start all numbered list items with 1 so that steps are treated as a list. (If your numbering extends beyond 9, you’ll want to do a manual search for those numbers before you run this find/change. There’s probably a smarter way to do this…)

^[2-9]\.

Find headings with missing anchor hashes

We require {#anchor} not {anchor}.

\#(.+?)\{[^#](.+?)\}

Find markdown components with extra space

In Experience League, we don’t allow a space between > and [! in extension syntax. In other words, we accept >[!NOTE] but not > [!NOTE]. Use this search to find these unwanted spaces, and remove them.

^>\s+\[!

Post-migration cleanup searches post-migration-cleanup

You can use these Visual Studio Code search techniques to find common issues that appeared when the files were migrated. When it’s difficult to find errors in Visual Studio Code searches, you can use search patterns in Google to locate problems.

Visual Studio Code Searches

Here’s a list of searches in Visual Studio Code that help identify common formatting problems. Feel free to add to this list.

Basic (non-expression) searches

Use these basic searches in Visual Studio Code to find common formatting errors.

Find “the the”

Find any bad bolds before [!DNL] or [!UICONTROL]

Find failed bold in definition lists

Expression-based searches

For these search expressions, make sure that you turn on the Use Regular Expressions option.

Find any ** preceded by a space at the end of a line

Find any ** followed by a space at the beginning of a line

Find [!DNL] or [!UICONTROL] in HTML tables

These errors are usually the result of a global Find/Change that failed to account for HTML. Remember, Markdown syntax isn’t supported in HTML.

Find Markdown links in HTML tables

Here’s another problem caused by an overly greedy Find/Change.

Google Searches

If you do a search in Visual Studio Code for "** " or “>”, the improper uses get lost among all the proper uses. With a Google search, it’s much easier to search for formatting that failed to render properly.

In these examples, using the site:experienceleague.adobe.com parameter narrows the search to our help content. You can further narrow the search by adding your specific help domain, such as site:experienceleague.adobe.com/content/help/en/target.

Find the failed instances of bold ** syntax

Find unformatted [!UICONTROL]/[!DNL] tags

Find unescaped escape characters

Keyboard shortcuts for Visual Studio Code shortcuts

You can use existing VS Code keyboard shortcuts, create your own custom shortcuts, and use shortcuts from an excellent add-on.

Editing keyboard shortcuts edit-keyboard-shortcuts

You can edit existing keyboard shortcuts. This is especially useful if you’ve added the Adobe Markdown Authoring extension and want to use different keyboard shortcuts.

In this example, I replaced the default ‘Toggle Tip’ shortcut (which is available because of the Adobe Markdown Authoring extension) with Control+Shift+Option+T. After I did that, the new shortcut appeared in the context menu.

See Key Bindings for Visual Studio Code (Microsoft documentation) for details.

Creating custom keyboard shortcuts for markdown extensions shortcuts-extensions

Consider adding your own keyboard shortcuts for common tasks. Here’s how.

Advanced version that applies UICONTROL and DNL to selection

Most writers would rather apply UICONTROL and DNL tags to a selection of text instead of inserting the tags at the cursor. To get the keystroke to work with a selection, you need to use a combination of snippets and shortcuts. It’s a little more advanced, but not that difficult. Here’s how to set that up.

If you create a snippet for UICONTROL and DNL, we recommend that you use different keystrokes (such as Ctrl+u and Ctrl+d) for selected text, as instructed. Then you can use one keystroke for applying to a selection and another keystroke (ctrl+shift+u and ctrl+shift+d) to insert the syntax at the cursor. Additionally, you can create a snippet for when you want to also apply bold formatting to your UICONTROL selection.

Custom keyboard shortcut quick reference

The following table shows the keyboard shortcuts that we used in the above examples. Make the appropriate adjustments if you edited your shortcuts to avoid system conflicts.

Additional keystrokes to consider creating

Comments

If you want to wrap selected text in comment syntax (<!-- -->), here’s the snippet syntax:

{
  "comment": {
  "scope": "markdown",
  "prefix": "comment",
  "body": [
      "<!-- $TM_SELECTED_TEXT -->"
  ],
  "description": "Wrap selection with comment tags"}
}

And here’s the section you could add to the keybindings.json file:

{
    "key": "ctrl+shift+h",
    "command": "editor.action.insertSnippet",
    "args": { "name": "comment" },
    "when": "editorHasSelection"
}

Shortcuts for commands such as slugify or lowercase

Visual Studio Code has many editing actions you can take advantage of. For example, if you want to create anchor IDs from heading text, you can run the “Slugify selection” command to convert headings (such as Creating visual elements) into anchor format (such as creating-visual-elements). Or, you can change the case of selected text.

Here’s how to assign keyboard shortcuts to VSC commands.

Using the AdobeDocs Chrome Extension

Sean’s team created a wonderful Chrome extension (thanks David and Daniel!) that lets you do the following:

Installing the extension

Using the extension

Specifing advanced options

Specifying advanced options lets you open files in Visual Studio Code from the browser and view analytics.

Renaming, Moving, and Deleting Files

See Moving, renaming, and restructuring content

Working with Tables tables

See Tables

Adding redirects

See Redirects

Experimenting with test content

Feel free to use the sandbox.en repo to experiment with the Git workflow or test out Markdown syntax. The sandbox repo should be clean and small. Feel free to edit or remove any content.

If you value any sandbox content, save a backup. We want to keep this repo clean, so remove content whenever we need to.