Authoring best practices

Feel free to jump in and add tips and best practices.

Tips and rules to prevent common errors

File and folder names

• Markdown filenames must be lowercase with hyphens. No capital letters, underscores, periods, or spaces. However, although not recommended, assets such as image files can include capital letters and underscores.

Articles

• Discrete components such as headings, fenced code blocks, and bullet/number lists should be surrounded by blank lines.
• Only a single h1 heading (#) 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).
• No duplicate heading IDs (anchor IDs) are allowed in a document.
• Heading IDs should not include periods. Bad example: {#version-2.3} Good example: {#version-2-3}
• No space between the markers of the text or surrounding the links e.g. abcd or [ abcd ]

TOC

• Every section heading in the TOC must have a valid section ID. Bad example: + Processing rules Good example: + Processing rules {#processing-rules}
• A section heading (parent) in the TOC cannot be a link.
• You must use proper syntax for TOC section headings (e.g., + Processing rules {#processing-rules}) and TOC article links (e.g., + [Article name](article.md)).
• Avoid adding the same file multiple times to a TOC (or to multiple TOCs). Doing so causes odd behavior.

Visual Studio Code tips

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

Adobe Markdown Authoring extension

We’re currently testing this extension pack and preparing to upload it to the Market for easy access.

• JIRA story

1. Do the following:

   • Uninstall any previous version of Adobe Markdown Authoring.
   • Disable any preview extension you may have installed.
   • Disable Markdown Shortcuts by mdickin if you installed it to avoid duplicated shortcuts.
   • Make sure markdownlint is installed.

2. To install the extension, right-click this link to download the adobe markdown authoring .vsix file.

3. In VSC, run ‘Install from VSIX’ and specify the .vsix file you downloaded.

4. Test. Provide feedback to Bob or Alva.

5. When the extension is available in the marketplace, remove this extension before installing the marketplace version.

Visual Studio Code add-ons we like

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.

Using the Command palette

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.

Linking tips

See the Linking tips article.

Global Find/Replace

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

1. Make sure that your cloned repo is in sync with the master branch on the server.
2. Choose File > Open, and open the folder containing the repo, user guide, or section that you want to search.
3. Choose Edit > Replace in Files. Specify the text you want to search for and what you want to replace it with.

1. Do any of the following:

   • Click the Replace All icon next to the Replace box to replace all occurrences across all files.
   • Click the Replace All icon next to the filename to replace all occurrences in that file.
   • Click the Replace icon next to the occurrence to replace only that instance.
   • Click the 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.

Wildcard Find/Replace

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.

Use (.+?) for wildcard search text and $1 for replacing with the same wildcard content.

1. Choose File > Open, and open the folder containing the repo, user guide, or section that you want to search.

2. Choose Edit > Replace or Replace in Files.

3. (Important) Click the Use Regular Expression icon to the right of the search box.

4. 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.

5. 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.

Wildcard search examples

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/(.+?)"(.+?)>
![$2 image](assets/$2)

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 ![](assets/rule-regs.png) to become ![rule-regs](assets/rule-regs.png)

!\[\]\(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.

^[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+\[!

Post-migration cleanup searches

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”

• Syntax: “the the” (with “Match Case” selected and surrounding spaces)
• Problem: “Time zone of the the data workbench server”
• Should be: “Time zone of the data workbench server”

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

• Syntax: ** [!
• Problem: ** [!DNL Visitor Page Views]**
• Should be: **[!DNL Visitor Page Views]**

Find failed bold in definition lists

• Syntax: "* ** " (add space after **)
• Problem: * ** [!DNL Longitude] column:** This column...
• Should be: * **[!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>
  

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: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

• &gt; site:experienceleauge.adobe.com/content/help/en/<myrepo>
• &lt; site:experienceleauge.adobe.com/content/help/en/<myrepo>
• &nbsp; site:experienceleauge.adobe.com/content/help/en/<myrepo>
• &amp; site:experienceleauge.adobe.com/content/help/en/<myrepo>

Keyboard shortcuts for Visual Studio Code

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

• Mac VS Code keyboard shortcuts
• Windows VS Code keyboard shortcuts

Creating custom keyboard shortcuts for markdown extensions

Until the Adobe Markdown Authoring extension pack is ready, consider adding your own keyboard shortcuts for common SCCM tasks. Here’s how.

1. Choose Code > Preferences > Keyboard Shortcuts.

2. Click the icon for editing shortcuts.

   

3. Copy and paste the shortcuts below, and save the keybindings.json file.

4. 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.

   NOTE

   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": "![](assets/)" },
            "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.

1. Create a snippet for UICONTROL with bold. This shortcut wraps the selection in UICONTROL and applies bold formatting to the selection.

   1. Choose Code > Preferences > User Snippets > New Global Snippets file.

   2. Specify a name such as uicontrol with bold and press Enter.

   3. 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"}
      }
      

   4. Save the snippet file.

2. 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"}
   }
   

3. Create a similar snippet for DNL.

   {
      "dnl": {
      "scope": "markdown",
      "prefix": "dnl",
      "body": [
         "[!DNL $TM_SELECTED_TEXT]"
      ],
      "description": "Wrap selection with dnl"}
   }
   

4. 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"
        }
   

5. Test the keyboard shortcuts in a different file with selected text. Again, replace any keyboard shortcuts that are already taken on your system.

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.

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

Useful Markdown Shortcut add-on links

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.

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.

1. Identify the command you want to use.

   In VSC, press Ctrl+Shift+P and begin typing the command you want to use.

2. Choose Code > Preferences > Keyboard Shortcuts.

3. In the search box, type the name of the action, such as “Slugify selection” or “Transform to Lowercase.”

4. Click the plus sign next to the action and specify your keystroke.

More?

Add your favorites here.

Renaming, Moving, and Deleting Files

See Moving, renaming, and restructuring content

Working with 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.