Extend, Customize, and Collaborate on the Help for Dynamics 365 Business Central

The source files for the Help for the base application are available in public GitHub repos so that you can easily extend and customize the content for your customers. In this section, you can learn about working with the GitHub repos and MarkDown files. You can also find guidance in the Docs Contributor Guide.

Tip

If you want to get Microsoft's content and deploy it to your own website with or without customizations, see Custom Help Toolkit.

Get content from the GitHub repos

There are repos in GitHub for the source content and each of the languages that Microsoft translates to. The dynamics365smb-docs repo contains the source content in English (US). If you want access to the content in other languages, navigate to the relevant repo - the names follow this pattern: dynamics365smb-docs-pr.<language>-<country>, such as dynamics365smb-docs-pr.da-DK for the Danish version.

You can use the HtmlFromRepoGenerator tool to get the latest version of Microsoft's content and generate HTML files that you can then customize. The tool handles the GitHub work for you, but you will still have to understand the basics of the Microsoft GitHub repos.

When Microsoft publishes an update to the content, the main branch in the corresponding GitHub repo is updated. The source repo is updated at least weekly; however, the related language-specific repos are updated less frequently, based on when new translations are made available. You can use the Custom Help Toolkit to get the current version of Microsoft's content and prepare HTML files for customization.

Alternatively, if you customize the Microsoft content based on MarkDown, you can use scripts to get the current version. The GitHub platform and tooling will help you manage any potential merge conflicts if you have made changes to the same files as Microsoft has. For more information, see Set up Git repository locally for documentation in the Docs Authoring Guide and Fork a repo in the Help for GitHub.

Important

In April 2021, the default branches in the public repos have been renamed from live to main . If you have any scripts that rely on the live branch, please update them to rely on main instead.

Tip

You do not have to get acquainted with GitHub if you just want to get the Microsoft content in HTML format to deploy to a website, for example. You do not even have to get a GitHub account, as shown in the Getting by without GitHub section. However, in many scenarios, you might want to join us in GitHub for closer collaboration and easy of extensibility.

If you fork one of our repos, you can choose to update your fork with regular updates from the Microsoft repo.

Both the source repo, dynamics365smb-docs, and the translation repos, such as dynamics365smb-docs-pr.da-dk, dynamics365smb-docs-pr.de-de and dynamics365smb-docs-pr.it-it, contain packages of MarkDown files for major versions and snapshots of the docs for the previous minor version. This is particularly useful if you deploy Business Central on-premises, since the repos by default reflect the latest version of Business Central online.

For example, navigate to the equivalent of https://github.com/MicrosoftDocs/dynamics365smb-docs-pr.da-DK/releases, and then get the release that you need for your solution.

For guidance about what the Microsoft-provided content for Business Central is all about, see User Assistance Model.

The remaining sections of this article are intended for people who do not use the Custom Help Toolkit - and for the curious. See the following table to find what you want to learn more about.

To learn more about this subject Read this section
Files and subfolders in the GitHub repos What the GitHub repos contain
How to interact with the GitHub repos without using the HtmlFromRepoGenerator tool Get updates from Microsoft
The mechanics of working in GitHub based on our internal contributor guide Get started with GitHub
How you can contribute to Microsoft's content Contributing
Forking a repo without using the HtmlFromRepoGenerator tool Get the content without a GitHub account
Generating content for your website without using the HtmlFromRepoGenerator tool Build HTML files
Potential problems you might see when you customize Microsoft's content Known issues with Microsoft's content
Using the Dynamics 365 Translation Service to manage translations Translate the content

What the GitHub repos contain

Microsoft's GitHub dynamics365smb-docs repos for Business Central Help contain the following folders:

  • archive

    Contains files that are not published but kept for backwards compatibility use internally at Microsoft. You can ignore this folder.

  • business-central

    Contains files that are relevant for Business Central

  • media-source

    Contains source files for some of the pictures that are used in the Business Central content

The repos also contain files in the root of the repos that are used internally by Microsoft for managing the content on the docs.microsoft.com site and on GitHub. They are not relevant for the purpose of extending or customizing the content.

Tip

Both the source repo, dynamics365smb-docs, and the translation repos, such as dynamics365smb-docs-pr.da-dk, dynamics365smb-docs-pr.de-de and dynamics365smb-docs-pr.it-it, contain packages of MarkDown files for major versions and snapshots of the docs for the previous minor version. This is particularly useful if you deploy Business Central on-premises, since the repos by default reflect the latest version of Business Central online.

For example, navigate to the equivalent of https://github.com/MicrosoftDocs/dynamics365smb-docs-pr.da-DK/releases, and then get the release that you need for your solution.

If you want to contribute to the developer and administration content, clone or fork the https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb repo

Get updates from Microsoft

Microsoft makes frequent changes to the Business Central content, and those changes show up in the public GitHub repos. The base repo, MicrosoftDocs/dynamics365smb-docs, is updated weekly, and the translations are updated monthly. When you decide it is time to get the latest version of the content from Microsoft, you can do that using GitBash or GitHub Desktop. In the Help for GitHub, you can see an example of how this works in GitBash. In GitHub Desktop, just use the Merge into current branch menu item to pull changes from the origin into your fork.

However, if your solution is available in more than one country, then you are likely to want to make content available in multiple languages. Microsoft has a GitHub repo for each supported language, but the configuration files are only available in the English (US) source repo, MicrosoftDocs/dynamics365smb-docs.

The following script was developed by a Danish partner in order to get the Microsoft source for a number of languages, copy media files to the localization repos, and then build HTML files. The script is provided in agreement with the partner without further support.

$languages = $("da-dk","de-ch","de-de")
$git = "C:\Program Files\Git\cmd\git.exe"
$docfx = "C:\GitHub\DocFx\docfx.exe"
$365docs = "C:\GitHub\MSFT\dynamics365smb-docs"
$langDir = "c:\Working\help\dynamics365smb-docs-pr."

Start-Process -FilePath $git -ArgumentList "clone --single-branch --branch main https://github.com/MicrosoftDocs/dynamics365smb-docs.git" -WorkingDirectory "C:\working\help" -Wait
foreach ($language in $languages)
{
    $arguments = $("clone --single-branch --branch lmain https://github.com/MicrosoftDocs/dynamics365smb-docs-pr." + $language + ".git")
    Start-Process -FilePath $git -ArgumentList $arguments -WorkingDirectory "C:\working\help" -Wait
    Copy-Item $($365docs + "\business-central\docfx.json") $($langDir + $language + "\business-central")
    Copy-Item $($365docs + "\business-central\media") $($langDir + $language + "\business-central") -Recurse -Force
    Copy-Item $($365docs + "\business-central\LocalFunctionality") $($langDir + $language + "\business-central") -Recurse -Force
    Copy-Item $($365docs + "\Templates") $($langDir + $language) -Recurse -Force
    Set-Content -Path $($langDir + $language + "\business-central\docfx.json") -Value (get-content -Path $($365docs + "\business-central\docfx.json"))
    Start-Process -FilePath $docfx -ArgumentList $("C:\working\help\dynamics365smb-docs-pr." + $language + "\business-central\docfx.json" + " --output c:\working\output\" + $language)
}

For more information, see the Build HTML files section.

Because the Microsoft repos are public, you do not need a valid GitHub account in order to get the content. However, we recommend that your organization has a system account with access to GitHub at a minimum.

Get started with GitHub

To join Microsoft in the world of GitHub and MarkDown, there are new terminology and tools to get used to. The following list outlines the main steps, but you can find additional content, tools, and ideas in the GitHub documentation and other forums.

  1. Fork the right repo

    You cannot work directly in the Business Central repos in the MicrosoftDocs GitHub org, such as the dynamics365smb-docs repo. The first thing you need to do is create a fork of the repo under your GitHub account. A fork is a copy of this repo that lets you work freely on the content without affecting the MicrosoftDocs/dynamics365smb-docs repo.

    Alternatively, you can clone the Microsoft repo. This is useful if you don't intend to customize Microsoft's content, for example. But in many cases, forking the repo is more preferable.

    For more information, see Set up your GitHub account and Set up Git repository locally for documentation in the Docs Authoring Guide.

    Tip

    You are not required to make your GitHub repos public. When you fork a public repo, you can specify in the settings for the new repo if the repo is public, private, or available only to specific GitHub accounts.

  2. Install GitHub Desktop (optional) and clone your forked repo.

    GitHub Desktop makes is easy to work and collaborate with repos locally from your own desktop. For more information, see GitHub Desktop.

  3. Get hold of your favorite MarkDown editor, and start making changes.

    The help content is stored in the business-central folder of the repo. Articles use a syntax for formatting text called Markdig Flavored Markdown, which is CommonMark compliant. To learn more about working with markdown, see Getting started with writing and formatting on GitHub.

    If you want to work locally, you can edit using any text editor. Just save the file as a .md type. Here are two good tools that provide you with some nice features, including a preview of how the content will be rendered in HTML:

Internally at Microsoft, some authors use Code, others use Atom, and for light-weight work, we tend to just edit the content in the browser. You can find more guidance for how to get started with MarkDown in the Docs Contributor Guide. This guide is published by the team that built the Docs.microsoft.com site where the Business Central team publishes their docs.

Get the content without a GitHub account

If you do not want to collaborate with Microsoft on the content, you can get the latest version of the content from GitHub without a GitHub account. For example, if you want content that is newer than the content on the Business Central installation media, you can get the latest by simply downloading the content of the relevant GitHub repo, which you can do without a GitHub account - the Microsoft repos are public so that anyone can always get to them. Use the HtmlFromRepoGenerator tool, create your own scripts, or follow this process to fork a repo manually.

To get files without a GitHub account

  1. Go to the relevant GitHub repo, such as this one for German: https://github.com/MicrosoftDocs/dynamics365smb-docs-pr.de-de/.

    You can see in the browser when the content was last updated. Alternatively, go to the releases tab and choose the package that you need for your solution. For more information, see What the GitHub repos contain.

  2. Choose the green Clone or download button, and then choose Download ZIP.

  3. Open the downloaded dynamics365smb-docs-pr.de-de-main.zip file and extract to a relevant location.

    Now you have a copy of Microsoft's content. Next, you can generate HTML files for use on your website as described in the Build HTML files section.

Build HTML files

For publishing to your own website, you can use the HtmlFromRepoGenerator tool that is part of the custom Help toolkit for Business Central to clone a repo and generate the corresponding HTML files.

Alternatively, you can create your own tooling and processes around DocFx, which is an open-source tool for converting markdown files. This section provides some guidance on how you can use DocFx to publish HTML files from your fork of one of the Microsoft repos without using the HtmlFromRepoGenerator tool. You can find additional tips in the Custom Help Toolkit article.

Tip

You can also use DocFx to generate content for the legacy Dynamics NAV Help Server. In that case, use the NAV docfx.json file from dynamics365smb-docs.

  1. Install DocFx on your computer.

    DocFx is a command line tool, but you can also run it from a PowerShell script.

    You must provide a .JSON file that defines certain build settings, including the output folder in which to store the generated HTML files. We suggest that you use the docfx.json configuration file from the dynamics365smb-docs repo. For more information, see Getting Started with DocFX.

  2. To change settings in the docfx.json file, open the docfx.json file from the folder containing your local clone in your preferred editor.

    The following table describes key parameters for you to customize.

    Property Description
    dest Specifies the output folder of the generated HTML files, such as c:\Working\output\.
    template Specifies the templates that the HTML files will be generated after. The default for Microsoft is blank, but the value can be a string or an array.
    globalMetadata Contains metadata that will be applied to every file, in key-value pair format. You can also add other global metadata, or metadata that applies to specific subfolders.
    fileMetadata Contains metadata that will be applied to specific files, based on the specified parameters, in key-value pair format. The default is currently blank.
    markdownEngineName Specifies the "flavor" of MarkDown to use to build the HTML files. The default is markdig.

    For more information, see the Properties for build section in the DocFx user manual.

    The docfx.json files in the Microsoft repos have additional settings for the docs.microsoft.com site. If you build the HTML files based on the docfx.json in the Microsoft repos, make sure that you have configured it for your needs.

    For example, in the globalMetadata section, set the ROBOTS property. We encourage you to use apply the ROBOTS: NOINDEX, NOFOLLOW metadata to any customized versions of Microsoft's content. The intent is that search engines will find Microsoft's original content on the docs.microsoft.com site rather than any customizations that you and hundreds of other may have published. Set the metadata in the individual files, or set it in the globalMeta section of docfx.json if you build using docfx.exe. For an example, see the ui-work-with-notes.md file in GitHub, which we have deprecated but kept in the repo as an example.If you use the docfx.json file to build HTML files for non-Microsoft functionality, then set the value of the ROBOTS property when you build Microsoft's content. You can also add other global metadata, or metadata that applies to specific subfolders.

  3. If you have cloned a localization repo such as dynamics365smb-docs-pr.da-dk, you must also clone the dynamics365smb-docs repo and copy the content of the \business-central\media\ folder.

    The localization repos only contain the files that are translated into the relevant languages. Microsoft does not translate all illustrations; therefore, the localization repos do not contain the many untranslated images, screenshots, and other illustrations. If you build a localization repo as-is, then the HTML files will have broken links to the missing illustrations.

    In the sample script described above, the following command copies the media folder:

    Copy-Item $($365docs + "\business-central\media") $($langDir + $language + "\business-central") -Recurse -Force
    
  4. Go to your desktop and open a command prompt.

  5. Go to the docfx installation folder.

  6. Run the equivalent of the following command:

    docfx "c:\GitHub\MSFT\dynamics365smb-docs\business-central\docfx.json"
    

The files are generated as .html files and stored in the output location that is specified in the docfx.json file.

Important

Depending on the website that the HTML files will be deployed to, you might not be able to use the table of contents file (TOC.html) that is generated in this process. That file is structured based on the configuration of the https://docs.microsoft.com site. If you use the legacy Dynamics NAV Help Server, then you must use the ToC.xml file instead.

The table of contents on the docs.microsoft.com site is currently a MarkDown file, TOC.md, but we are planning to convert it to a YAML file in order to be more compliant with the docs.microsoft.com site. Once we have converted the TOC.md file to TOC.yml, you will still be able to use DocFx.exe to build HTML files, but you will have to port your customizations of the TOC.md file to the new YAML format.

The root of the MicrosoftDocs repos contain files that are related to internal Microsoft processes, such as .openpublishing.build.ps1. These scripts are used to validate and preview content, but they rely on internal Microsoft resources that are not publicly available. The .openpublishing.redirection.json file lists files that were published to the docs.microsoft.com site but have been deprecated later. As part of standard website practices, the docs.microsoft.com site uses redirection to avoid broken links when a page is deleted, and the .openpublishing.redirection.json file provides the mapping for redirection.

For inspiration for how to build your own help website, see How-to: Customize DFM Engine in the DocFx user manual and the Azure App Service documentation.

For tips and tricks about writing in MarkDown, see the Authoring Guide.

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.

Alternatively, you can add a post-processing step to the script that you use to run DocFx to change the equivalent of <h3 id=da-DK-anchor-name> with <h3 id=en-US-anchor-name>. In this example, the step would change <h3 id=min-oversatte-overskrift'> to <h3 id=my-translated-subheading'>.

Known issues with Microsoft's content

Microsoft's content in the various GitHub repos is optimized for the docs.microsoft.com site and the tools that are used for this site. If you reuse Microsoft's content, you may experience a number of known issues, depending on how you publish your content. This section describes recommended steps to work around these issues.

Docs are not available for a specific version

Microsoft's public GitHub repos reflect the latest version of Business Central. If you want to deploy help for an earlier version of Business Central on-premises, then you can use the HTML files on the installation media. If you find that that particular version is missing content, then please check the following sections for suggested workarounds.

If you deploy Microsoft's content to a website, your tools or your users will report that some links do not work. The links result in a 404 error or similar. These errors are caused by Microsoft having deleted the target files due to rework of the content. On the docs.microsoft.com site, we have tools that automatically handle links to deleted files through redirection. But if you deploy Microsoft's content to your own website, you will not have the same redirection.

We run periodic tests to catch these errors, but if you do see an error that is caused by a file not existing anymore, check the .openpublishing.redirection.json file in the root of the source repo. This file is used by the docs.microsoft.com site to manage redirection when a file is deprecated. For example, if you get an error that "finance-how-to-set-up-sepa-direct-debit.md does not exist", then you can see in the .openpublishing.redirection.json file that the article has been deprecated and replaced by finance-collect-payments-with-sepa-direct-debit.md. You can replace the link in the file that is looking for finance-how-to-set-up-sepa-direct-debit.md to link to finance-collect-payments-with-sepa-direct-debit.md instead.

Tip

Use the HtmlFromRepoGenerator tool to manage this for you.

ToC.xml for Help Server is different from the TOC.md file

Microsoft does not currently maintain the ToC.xml file and does not add new features to it. While the Help Server component is still supported, it will be deprecated in 2021 release wave 1. As a result, it contains links that are broken as described in the previous section.

Translated content is not available

Microsoft creates content in English (US) that then gets translated into the Microsoft-provided target languages. The translations are available in the relevant localization repos within a few weeks.

Translate the content

You can use the Dynamics 365 Translation Service (DTS) to translate your own or the Microsoft-provided content into other languages. The service is hosted in Lifecycle Services and currently supports translation of content in Word documents and HTML files. For more information, see Translate documentation files.

To translate content for either Business Central or Dynamics NAV, choose Dynamics NAV as the product as shown in the following illustration:

Shows translation project for NAV or Business Central

Contributing

A benefit of GitHub is the ability for you to contribute to the core content that the Microsoft team provides in the dynamics365smb-docs repo. For example, you might have a new article that you think would be beneficial, or you might have a correction to an existing article. If you would like to contribute to the MicrosoftDocs/dynamics365smb-docs repo, you create a pull request from your repo to the MicrosoftDocs/dynamics365smb-docs repo. The Microsoft team will then review the request and include the changes as appropriate.

Note

Microsoft accepts pull requests to the dynamics365smb-docs repo only, not the language-specific repos. If you have feedback about translations, please report a GitHub issue in the relevant repo.

To create a pull request to the MicrosoftDocs/dynamics365smb-docs repo by using GitHub Desktop, do the following:

  1. Commit the changes to your repo that you want to include in the pull request.
  2. Choose Sync to push the changes up to your repo on GitHub.
  3. When the sync is completed, choose Pull Request, make sure that the pull request points at the origin/main branch, and then choose Pull Request.

Tip

If you want to request brand new content, we ask you to submit a request of type Documentation at https://aka.ms/bcideas.

See also

Business Central User Assistance Model
Configuring the Help Experience
Custom Help Toolkit
Custom Help Toolkit: The HtmlFromRepoGenerator tool
Custom Help Toolkit: The FieldTopicTextExtractor tool
Custom Help Toolkit: The HtmlLocaleChanger tool
Authoring Guide
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