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.

Get content from the GitHub repos

There are different 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.

When Microsoft publishes an update to the content, the live branch in the corresponding GitHub repo is updated. The source repo is updated weekly. The related language-specific repos are updated less frequently, based on when new translations are made available. If you fork one of our repos, you can choose to update your fork with updates from the Microsoft repo on a monthly basis or less frequently. 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.

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 Help Server website, for example. For more information, see the Getting by without GitHub section. However, if you want to extend or customize the Microsoft content, we recommend that you join us in GitHub.

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

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.

    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.

Important

The Writate plugin for Word can be very helpful for converting existing content to MarkDown, but we recommend that you do not use it to edit MarkDown files in Word. When you save the MarkDown file, all metadata tags and some of the formatting is erased.

What the GitHub repos contain

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

  • accountant

    Contains files that are relevant for Dynamics 365 — Accountant Hub

  • business-central

    Contains files that are relevant for Business Central

  • invoicing

    Contains files that are relevant for Microsoft Invoicing

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

Note

The Business Central installation media contain CAB files for Help Server. However, you can always get newer content from the GitHub repos. If you find that the CAB files are outdated, or if they do not contain the files that you expect, you can get the latest files from GitHub. For more information, see the Get updates from Microsoft and Get the content without a GitHub account sections, respectively.

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. But you can choose to get updates monthly, twice a year, or once a year, for example. That is entirely up to you.

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. To help you get the content that you need, you might want to run a PowerShell script that picks up content from the various GitHub repos.

The following example is based on a script that a Danish partner developed in order to get the Microsoft source for a number of languages, copy media files to the localization repos, and then build HTML files for the legacy Dynamics NAV Help Server. 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 live https://github.com/MicrosoftDocs/dynamics365smb-docs.git" -WorkingDirectory "C:\working\help" -Wait
foreach ($language in $languages)
{
    $arguments = $("clone --single-branch --branch live 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\NAVdocfx.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\NAVdocfx.json") -Value (get-content -Path $($365docs + "\business-central\NAVdocfx.json"))
    Start-Process -FilePath $docfx -ArgumentList $("C:\working\help\dynamics365smb-docs-pr." + $language + "\business-central\NAVdocfx.json" + " --output c:\working\output\" + $language)
}

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.

See also the Build HTML files section.

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 what is called 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, you can report a GitHub issue in the relevant repo.

For example, 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. Alternatively, here is the command for Git Shell:

    git add -u
    git commit -m "update doc"
    git push
    
  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 live branch, and then choose Pull Request.

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.

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.

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

  3. Open the downloaded dynamics365smb-docs-pr.de-de-live.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 Help Server or elsewhere as described in the Build HTML files section.

Build HTML files

For publishing to your own website, you can use tools such as DocFx. DocFx is an open-source tool for converting markdown files, such as if you want to preview your content locally, or to generate content for a website. This section provides some guidance on how you can use DocFx to publish HTML files for the Dynamics NAV Help Server.

Tip

You can also use DocFx to generate content for other websites. In that case, either modify NAV docfx.json or replace NAVdocfx.json with your own configuration file to meet your website's requirements.

  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 NAVdocfx.json configuration file from the dynamics365smb-docs repo. However, it is configured for use with the legacy Dynamics NAV Help Server. To configure it for use with a different website, remove or replace the value of the template property.

    Alternatively, create your own docfx.json file based on the setup of your website. For more information, see Getting Started with DocFX.

  2. To change settings in the NAVdocfx.json file, in the folder where your local clone is, such as C:\GitHu b\MSFT\dynamics365smb-docs\business-central, open the NAVdocfx.json file in your preferred editor.

    The following table describes key parameters.

    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 value can be a string or an array.
    globalMetadata Contains metadata that will be applied to every file, in key-value pair format. In the NAVdocfx.json file, this property applies the ROBOTS: NOINDEX, NOFOLLOW metadata to each HTML file. 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. If you use the NAVdocfx.json file to build HTML files for non-Microsoft functionality, then change the value of the ROBOTS property. You can also add other global metadata, or metadata that applies to specific subfolders.
    markdownEngineName

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

    The Microsoft repos also contain a docfx.json file that has a different settings because the repos are configured 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.

  3. If you have cloned a localization repo such as dynamics365smb-docs-pr.da-dk, you must also clone the dynamics365smb-docs repo and then 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, and 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\NAVdocfx.json"
    

The files are generated as .html files and stored in the specified output.

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

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

See also

Business Central User Assistance Model
Configuring the Help Experience
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