Feel free to jump in and add tips and best practices.
File and folder names
Articles
#
) is allowed in the document, and all later headings are h2 (##
) or lower level headings. First line in the file below the metadata should be h1 (top level heading, or title).{#version-2.3}
Good example: {#version-2-3}
abcd
or [ abcd ]
TOC
+ Processing rules
Good example: + Processing rules {#processing-rules}
+ Processing rules {#processing-rules}
) and TOC article links (e.g., + [Article name](article.md)
).If you’re using Visual Studio Code for editing, here are some tips and techniques that we’ve found useful.
We’re currently testing this extension pack and preparing to upload it to the Market for easy access.
Do the following:
To install the extension, right-click this link to download the adobe markdown authoring .vsix file.
In VSC, run ‘Install from VSIX’ and specify the .vsix file you downloaded.
Test. Provide feedback to Bob or Alva.
When the extension is available in the marketplace, remove this extension before installing the marketplace version.
Extension | Description |
---|---|
Markdown Preview GitHub Styling | Adds a preview option in VSC that’s similar to Git-flavored preview. Do not install if you’re using Adobe Markdown Authoring extension. |
Markdown Shortcuts | Shortcuts toolbar for bold, italics, and bullet lists. The Adobe Markdown Authoring extension will make this obsolete. |
markdownlint (highly recommended) | Flags content for possible validation errors based on lint, which we use in Jenkins. |
Table Formatter | Useful for making small, basic tables easier to read. |
Spell Right | Standard spell checker. |
Bracket Pair Colorizer 2 | Highlights bracket and brace pairs. Useful for links and TOC editing. |
Copy Relative Path Posix (for Windows users) | In Windows, copying the relative path using this command uses / instead of \ , which is necessary for root links. |
Paste Image | Paste image directly from clipboard to markdown, adding the file and creating an image link. See the add-on instructions. |
Feel free to add any extension to this list that you find useful.
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.
Keep in mind that there are many duplicate filenames, especially in solutions with multiple guides, so make sure you’re editing the right file.
See the Linking tips article.
Visual Studio Code lets you find/change text either within a document or across all the files you have open.
Do any of the following:
x
icon next to any occurrance to remove it. This will exclude it from any Replace All action.When you use the Replace in Files feature, replacing items automatically saves the affected files.
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.
Watch the Wildcard Expressions video
Use (.+?)
for wildcard search text and $1
for replacing with the same wildcard content.
Choose File > Open, and open the folder containing the repo, user guide, or section that you want to search.
Choose Edit > Replace or Replace in Files.
(Important) Click the Use Regular Expression icon to the right of the search box.
Specify the search string using (.+?)
for wildcard.
The parentheses indicate a group. The dot .
indicates a wildcard. The plus sign +
indicates multiple characters. The question mark ?
tells it not to be greedy so that the string ends with the first instance of whatever comes after the group.
Specify the replace string using $1
where you want the wildcard text to appear.
The $1
returns wildcard text was stored in the first group.
Here are some useful strings for converting the loc tags in HTML table content.
search/replace keyword tags
<span class="keyword"> (.+?)</span>
[!UICONTROL $1]
search/replace uicontrol tags
<span class="uicontrol"> (.+?)</span>
**[!UICONTROL $1]**
search/replace wintitle tags
<span class=“wintitle”> (.+?)</span>
[!DNL $1]
search/replace links
<a href="(.+?)"(.+?)> (.+?)</a>
[$3]($1)
In this case, 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/(.+?)"(.+?)>

You might need to tweak this one 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 this example, we want to find HTML links that start with something other than a href
.
\{[^#](.+?)\}
In this example, we want to find anchor IDs that are missing the #
character.
&search replace [ ]
in headings
We’ll use [!DNL]
as an example…
\# (.+?) \[!DNL(.+?)]
# $1$2
Use \
to escape characters such as #
and [
used in expressions.
Search replace underscores in anchor links
In this example, the migration tool mistakenly used underscores instead of hyphens in anchors, even though the target anchors were hyphenated. So we needed to replace all anchor links by running this global find/change multiple times.
.md#(.+?)_(.+?)\)
.md#$1-$2)
Copy empty alt text with image name
For example, you want 
to become 
!\[\]\(assets/(.+?)\.(.+?)\)

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.
^[2-9]\.
Find headings with missing anchor hashes
We require {#blah}
not {blah}
.
\#(.+?)\{[^#](.+?)\}
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+\[!
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.
Here’s a list of searches in Visual Studio Code that help identify common formatting problems. Feel free to add to this list.
Use these basic searches in Visual Studio Code to find common formatting errors.
Find “the the”
the the
” (with “Match Case” selected and surrounding spaces)Find any bad bolds before [!DNL]
or [!UICONTROL]
** [!
** [!DNL Visitor Page Views]**
**[!DNL Visitor Page Views]**
Find failed bold in definition lists
* **
" (add space after **
)* ** [!DNL Longitude] column:** This column...
* **[!DNL Longitude] column:** This column...
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
Syntax:
^(.+?) \*\*$
Problem: **Period-Based Unique Visitors Reports **
Should be: Period-Based Unique Visitors Reports
Find any **
followed by a space at the beginning of a line
Syntax:
^\*\* (.+?)
Problem: ** Next steps:** We will begin to migrate users
Should be: Next steps: We will begin to migrate users
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.
Syntax: <p(.+?)\[!
Problem:
<td colname="col2"> <p>Replaces the <span class="uicontrol"> Show Metrics</span>
popup in [!UICONTROL Reports & Analytics]. </p>
Should be:
<td colname="col2"> <p>Replaces the <span class="uicontrol"> Show Metrics</span>
popup in <span class="uicontrol"> Reports & Analytics</span>. </p>
Find Markdown links in HTML tables
Here’s another problem caused by an overly greedy Find/Change.
Syntax: <p(.+?)\]\(
Problem:
<td colname="col2"> <p>If your site contains links to files with any
of the listed extensions, the URLs of these links will appear in
reporting. See [Configuration Variables](js-implementation
/c-variables/configuration-variables.md). </p> </td>
Should be:
<td colname="col2"> <p>If your site contains links to files with any
of the listed extensions, the URLs of these links will appear in
reporting. See <a href="/docs/authoring-guide-exl/implement/js-implementation/c-variables
/configuration-variables.md"> Configuration Variables</a>. </p> </td>
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:experienceleauge.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:experienceleauge.adobe.com/content/help/en/target
.
Find the failed instances of bold **
syntax
** ** site:experienceleauge.adobe.com/content/help/en/
<myrepo>
Find unformatted [!UICONTROL]
/[!DNL]
tags
UICONTROL site:experienceleauge.adobe.com/content/help/en/
<myrepo>
DNL site:experienceleauge.adobe.com/content/help/en/
<myrepo>
Find unescaped escape characters
> site:experienceleauge.adobe.com/content/help/en/
<myrepo>
< site:experienceleauge.adobe.com/content/help/en/
<myrepo>
site:experienceleauge.adobe.com/content/help/en/
<myrepo>
& site:experienceleauge.adobe.com/content/help/en/
<myrepo>
When the Adobe Markdown Authoring extension, custom shortcuts for adding notes and uicontrol/dnl tags will be available. You can edit these shortcuts. More info to follow.
You can use existing VS Code keyboard shortcuts, create your own custom shortcuts, and use shortcuts from an excellent add-on.
Until the Adobe Markdown Authoring extension pack is ready, consider adding your own keyboard shortcuts for common SCCM tasks. Here’s how.
Choose Code > Preferences > Keyboard Shortcuts.
Click the icon for editing shortcuts.
Copy and paste the shortcuts below, and save the keybindings.json file.
Test the keyboard shortcuts in a different file.
You can switch between different windows to test the keystrokes and make/save edits. The shortcuts work in runtime.
In some cases, you might already have a function assigned to one or more of these keystrokes. You’ll need to find a different keyboard shortcut to get around the conflict.
keybindings.json file
[
{
"key": "ctrl+shift+u",
"command": "type",
"args": { "text": "[!UICONTROL ]" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+d",
"command": "type",
"args": { "text": "[!DNL ]" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+n",
"command": "type",
"args": { "text": ">[!NOTE]\n>\n>" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+i",
"command": "type",
"args": { "text": ">[!IMPORTANT]\n>\n>" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+c",
"command": "type",
"args": { "text": ">[!CAUTION]\n>\n>" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+w",
"command": "type",
"args": { "text": ">[!WARNING]\n>\n>" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+t",
"command": "type",
"args": { "text": ">[!TIP]\n>\n>" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+v",
"command": "type",
"args": { "text": ">[!VIDEO](url)" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+m",
"command": "type",
"args": { "text": ">[!Related Articles]\n>\n>* [article](url)\n>* [article](url)" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+a",
"command": "type",
"args": { "text": "" },
"when": "editorTextFocus"
},{
"key": "ctrl+shift+l",
"command": "type",
"args": { "text": "<ul><li>Item1</li><li>Item2</li></ul>" },
"when": "editorTextFocus"
}
]
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.
Create a snippet for UICONTROL with bold. This shortcut wraps the selection in UICONTROL and applies bold formatting to the selection.
Choose Code > Preferences > User Snippets > New Global Snippets file.
Specify a name such as uicontrol with bold
and press Enter.
Paste the following code into the snippet:
{
"uicontrol-with-bold": {
"scope": "markdown",
"prefix": "uicontrol with bold",
"body": [
"**[!UICONTROL $TM_SELECTED_TEXT]**"
],
"description": "Wrap selection with uicontrol and apply bold formatting to selection"}
}
Save the snippet file.
Create a similar snippet for UICONTROL without bold.
{
"uicontrol-without-bold": {
"scope": "markdown",
"prefix": "uicontrol without bold",
"body": [
"[!UICONTROL $TM_SELECTED_TEXT]"
],
"description": "Wrap selection with uicontrol"}
}
Create a similar snippet for DNL.
{
"dnl": {
"scope": "markdown",
"prefix": "dnl",
"body": [
"[!DNL $TM_SELECTED_TEXT]"
],
"description": "Wrap selection with dnl"}
}
In the keybindings.json file (see above), add the shortcuts for UICONTROL with bold, UICONTROL without bold, and DNL.
{
"key": "ctrl+u",
"command": "editor.action.insertSnippet",
"args": { "name": "uicontrol-with-bold" },
"when": "editorHasSelection"
},
{
"key": "ctrl+n",
"command": "editor.action.insertSnippet",
"args": { "name": "uicontrol-without-bold" },
"when": "editorHasSelection"
},
{
"key": "ctrl+d",
"command": "editor.action.insertSnippet",
"args": { "name": "dnl" },
"when": "editorHasSelection"
}
Test the keyboard shortcuts in a different file with selected text. Again, replace any keyboard shortcuts that are already taken on your system.
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.
Shortcut | Extension | Notes |
---|---|---|
ctrl+shift+n | !NOTE |
|
ctrl+shift+i | !IMPORTANT |
|
ctrl+shift+c | !CAUTION |
|
ctrl+shift+w | !WARNING |
|
ctrl+shift+t | !TIP |
|
ctrl+shift+v | !VIDEO |
Paste video URL |
ctrl+shift+m | !Related Articles |
|
ctrl+shift+a | image link to assets folder | Edit if necessary |
ctrl+shift+l (letter L) | insert unordered list in table | |
ctrl+shift+u | !UICONTROL - Insert at cursor |
|
ctrl+u | !UICONTROL - Wrap around selected text and apply bold formatting |
If you created the snippet |
ctrl+n | !UICONTROL - Wrap around selected text, no bold |
If you created the snippet |
ctrl+shift+d | !DNL - Insert at cursor |
|
ctrl+d | !DNL - Wrap around selected text |
If you created the snippet |
If you have the Markdown Shortcuts add-on installed (recommended) for VS Code, note the following shortcuts:
Shortcut | Extension | Notes |
---|---|---|
ctrl+b | Toggle bold | |
ctrl+i | Toggle italics | |
ctrl+l (letter L) | Add hyperlink | Paste link into text field |
Check out the the Markdown Shortcuts add-on for details.
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.
Identify the command you want to use.
In VSC, press Ctrl+Shift+P and begin typing the command you want to use.
Choose Code > Preferences > Keyboard Shortcuts.
In the search box, type the name of the action, such as “Slugify selection” or “Transform to Lowercase.”
Click the plus sign next to the action and specify your keystroke.
More?
Add your favorites here.
See Moving, renaming, and restructuring content
See Tables
See Redirects
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.