Authoring Guide for Dynamics 365 Business Central

If you are contributing to the Business Central Help, or if you are customizing and extending the Microsoft content for your own solution, then you will probably want to use the same tools, processes, and style guide that Microsoft uses.

This page shows tips and tricks for authoring in MarkDown based on what the Business Central team of technical writers learnt when they started in MarkDown in 2015.

Resources

Authoring in Markdown

The Business Central content is styled using a MarkDown syntax as described below. You can also get a lot of guidance in the MarkDown Reference section in the Docs Contributor Guide.

Headings

Use # for headings. For more information, see Headings in the Docs Contributor Guide.

Bulleted lists

Use - to create bullets, for example:

The following options are available:

- first option
- second option
- third option

Tip

The Markdown validation in the current version of the Docs Authoring Pack recommends a blank line between options in a bulleted list.

Ordered lists

Use numbers for ordered lists. No space between the lines, we'll let the template for the documentation website take care of that.

1. Choose the ![Lightbulb that opens the Tell Me feature](media/ui-search/search_small.png "Tell me what you want to do") icon, enter **Payment Journal**, and then choose the related link.
2. In the **Payment Journal** window, on the first journal line, enter the relevant information about the payment entry.
3. To apply a single vendor ledger entry:
4. In the **Applies-to Doc. No.** field, choose the field to open the **Apply Vendor Entries** window.

Bold and italics syntax

Use **bold** and *italics*

Tables

For tables in the body, use the markdown syntax. The Docs Authoring Pack for Visual Studio Code has a shortcut for adding a table, and you can also use Tables Generator.

| To   | See                       |
|------|---------------------------|
|<text>|<link>|
| | |
| | |

For nested tables in ordered and unordered lists use HTML-syntax. Markdown does not support tables very well. If you use the markdown syntax the list will be broken, the table will align left and list will be renumbered.

Comment syntax

Useful for sections that are not ready and will not pass the build check.

<!-- Comments -->

Examples

<!-- [Managing Payables](payables-manage-payables.md)-->
<!-- This is a paragraph that spans more lines and I can just put the comment tag
at the beginning and end of it -->

Ordinary link to a different topic in the same folder

These links have the format [link text](filename.md).

Example: [Managing Payables](payables-manage-payables.md)

These links have the format [link text](subfolder/filename.md).

For example, you want to link to payables-manage-payables.md from ui-work-general-journals.md, where the folder structure is as follows:

  • articles
    • ui-work-general-journals.md
  • ManagePayables
    • payables-manage-payables.md

Here is the link: [Manage Payables](ManagePayables/payables-manage-payables.md)

These links have the format [link text](../folder/filename.md).

For example, you want to link to payables-manage-payables.md from receivables-manage-receivables.md, where the folder structure is as follows:

  • articles
    • ManageReceivables
      • receivables-manage-receivables.md
      • ui-work-general-journals.md
      • ManagePayables
        • payables-manage-payables.md

Here is the link: [Manage Payables](../ManagePayables/payables-manage-payables.md)

Link to a place in the same article

From within an article, you can create a link to a specific heading in the same article. You can create the link like other links except with the following format:

[link text](#target-heading)

target-heading is the text of the heading that you want to link to, except it is all lowercase and spaces between words are replaced with hyphens. For example, here is the link: [How Autoscaling Works](#how-autoscaling-works)

To the heading: ## How Autoscaling Works

Link to a place in a different article

From an article, you can create a link to a specific heading in another article. You can create the link like other links except with the following format:

[link text](targetarticlename#target-heading)

targetarticlename is the file name of the article, including the .md file type. target-heading is the text of the heading that you want to link to, except it is all lowercase and spaces between words are replaced with hyphens.

For example, to link to the heading "How Autoscaling Works" in the article Autoscaling.md", add the following code: [link text](Autoscaling.md#how-autoscaling-works)

If your website supports two or more locales, you can use DocFx to generate HTML files for the relevant languages. However, you may experience problems with links to anchors, also known as bookmarks.

For example, if your content has a link from article1.md to a specific section in article2.md, that link would be formatted like this: [My translated subheading](article2.md#my-translated-subheading). Then, when you run DocFx to generate HTML files in Danish, DocFx will convert that link to [Min oversatte overskrift](article2.md#min-oversatte-overskrift). That is not a problem because the link will work in both English and Danish.

But if you then want to use that link elsewhere, the link only works for one of the languages because the anchor changed its name in the Danish translation. If you link to that subheading in article2 from your marketing site or support site, or if you use it as the value of the ContextSensitiveHelpPage property, then it only works in English.

To work around this problem, we recommend that you create explicit anchors by tagging your subheading to give it a fixed anchor. The following example illustrates how that would look in MarkDown:

### <a name="subheading"></a>My translated subheading

You would then be able to use the same link across all locales: [My translated subheading](article2.md#subheading), which would render in HTML as myurl.com/docs/article2#subheading across all languages.

For more information, see Using hashtag in cross reference in the GitHub documentation.

Note

Adding fixed anchors is only relevant if you want to generate a link to a subheading that works consistently across languages.

Line breaks (soft return)

In the editor, add two blank spaces at the end of the sentence and hit return. This is used in the See Also list. (See Also must be heading 2.)

Continue steps after a non-step para

Enter four spaces in front of the non-step para. Otherwise, the non-step para will restart the step sequence.

TOC

The TOC structure of the TOC.md file is as follows:

#[Overview](overview.md)
 ##[Topic 1](topic-1.md)
 ##[Topic 2](topic-2.md)
 ##[Topic 3](topic-3.md)
 ##[Topic 4](topic-4.md)

Standard Phrases

All fields in Business Central have tooltips. Therefore, do not document fields in Help. To refer readers to the tooltips, use this standard phrase where relevant:

"Choose a field to read a short description of the field or link to more information."

For more information, see Business Central User Assistance Model.

Topic Titles

  • Use imperative verb form for step-based topics ("Pay vendors").
  • Use gerund verb form for conceptual, non-step topics. ("Paying Vendors")
  • Use nouns for highest-level topics. ("Sales")

File Naming

Rules

  • No spaces or punctuation characters. Use hyphens to separate the words in the file name.
  • Use all lowercase letters
  • No more than 80 characters - this is a publishing system limit
  • Use action verbs that are specific such as develop, buy, build, troubleshoot. No -ing words.
  • No small words - don't include a, and, the, in, or, etc.
  • All files must be in markdown and use the .md file extension.

Examples

Topic title Naming
Select a Company ui-how-select-company.md
Enter Criteria in Filters ui-enter-criteria-filters.md
Troubleshooting: Record Locked by Another User ui-troubleshoot-record-locked-another-user.md
Changing Basic Settings ui-change-basic-settings.md
Sales sales-manage-sales.md
Set Up Currencies finance-setup-currencies.md
Set Up Purchasers purchases-how-setup-purchasers.md
Understanding Session Timeouts admin-understand-session-timeouts.md
Manage Data Encryption admin-manage-data-encryption.md

Country-specific content

To simplify content localization and translation, country-specific articles live in country-specific folders. The TOC entries live under the "Local Functionality" parent node.

See also

Business Central User Assistance Model
Extend, Customize, and Collaborate on the Help
Configuring the Help Experience
Docs Contributor Guide
Docs Authoring Pack for Visual Studio Code
Getting started with writing and formatting on GitHub
Visual Studio Code
Atom
DocFx
Blog post: Extending and customizing the Help
Blog post: Collaborate on content for Business Central