Extend 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 Learn Contributor Guide.

Get content from the GitHub repos

Important

The HTMLFromRepoGenerator tool is being deprecated. To generate HTML files from Markdown, use another tool, such as DocFX.

The language-specific repositories are also being deprecated, and will no longer be available at the end of the 2022 calendar year.

The dynamics365smb-docs and dynamics365smb-devitpro repos contain the source content in English (US). When Microsoft publishes an update to the content, the main branch in the corresponding public GitHub repo is updated. Typically, the source repo is updated weekly.

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 easier extensibility.

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

The source repo, dynamics365smb-docs, contains packages of Markdown files for major versions and snapshots of the docs for the previous minor version.

For example, go to https://github.com/MicrosoftDocs/dynamics365smb-docs/releases to get the release that you need for your solution.

Guidance about what the Microsoft-provided content for Business Central is all about is available at User Assistance Model.

The following table lists some of the key subjects that you should know about.

To learn more about this subject Go to this section
Files and subfolders in the GitHub repos What the GitHub repos contain
How to interact with the GitHub repos 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 Get the content without a GitHub account
Generating content for your website Build HTML files
Potential problems you might have 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

    In the source repo only, this folder contains files that are not published but kept for backwards compatibility use internally at Microsoft. You can ignore this folder. The folder does not exist in the translation repos.

  • business-central

    Contains Markdown files with content that is relevant for business users, administrators, and consultants of Business Central

  • media-source

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

  • templates

    Contains three Markdown files that you can use as templates for your content. The templates define required metadata and a recommended structure of the content.

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

Tip

The source repo, dynamics365smb-docs, contains packages of Markdown files for major versions and snapshots of the docs for the previous minor version.

For example, go to https://github.com/MicrosoftDocs/dynamics365smb-docs/releases to 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. 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. The Help for GitHub offers 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.

The following script was developed by a Danish partner to perform the following tasks:

  • Get the Microsoft source for a number of languages
  • Copy media files to the localization repos
  • 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 main 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)
}

More information is available in 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, at a minimum, your organization has a system account with access to GitHub.

Get started with GitHub

To join Microsoft in the world of GitHub and Markdown, there are 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.

    Learn more at 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 whether 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. Learn more at 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 learn.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 a tool that can generate HTML files, 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: https://github.com/MicrosoftDocs/dynamics365smb-docs/.

    The browser will indicate when the content was last updated. Alternatively, go to the releases tab and choose the package that you need for your solution. Learn more at What the GitHub repos contain.

  2. Choose the green Code button, and then choose Download ZIP.

  3. Open the downloaded dynamics365smb-docs-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, use any third-party tool that can 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. Learn more at 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.

    Learn more at Properties for build section in the DocFx user manual.

    The docfx.json files in the Microsoft repos have additional settings for the learn.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 learn.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. Go to your desktop and open a command prompt.

  4. Go to the docfx installation folder.

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

DocFx is no longer used internally in Microsoft and does not support YAML and other changes that we're making to our content. 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://learn.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 learn.microsoft.com site but have been deprecated later. As part of standard website practices, the learn.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, go to How-to: Customize DFM Engine in the DocFx user manual and the Azure App Service documentation.

For tips and tricks about writing in Markdown, go to 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 learn.microsoft.com site and the tools that are used for this site. It is not intended to be customized directly but to be supplemented by articles on your local website. 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 learn.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 learn.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.

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 was deprecated in 2021 release wave 1. As a result, it contains links that are broken, as described in the Broken links section.

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. Learn more at 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 for Business Central. There is a lot of good advice and best practices published in the Microsoft Docs contributor guide. But this section provides information about how to apply that advice to the Business Central content.

We have two public GitHub repos that you can contribute to:

  • MicrosoftDocs/dynamics365smb-docs

    This repo contains a copy of the source files for the business functionality content that publishes at https://learn.microsoft.com/en-us/dynamics365/business-central

  • MicrosoftDocs/dynamics365smb-devitpro-pb

    This repo contains a copy of the source files for the developer and admin content that publishes at https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro

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 Business Central content on the Microsoft Docs website, you create a pull request from your repo to the target repo. The Microsoft team will then review the request and include the changes as appropriate.

Get started

If you want to suggest a minor (or major) change to an existing article, follow these steps:

  1. Find the published article, such as Using OData to Return or Obtain a JSON Document.

  2. In the top right corner of the article, choose the Edit button.

    Choosing the button takes you to the source file on GitHub. In this example, that's https://github.com/MicrosoftDocs/dynamics365smb-devitpro/blob/main/dev-itpro/webservices/return-obtain-json-document.md.

    Note

    If you're not already signed in with a GitHub account, you'll be prompted to sign in or create a new account. You cannot contribute to the Business Central content without a GitHub account.

  3. In the top right corner of the Markdown file, choose the pencil icon. Depending on who you are, you'll be taken to a fork of Microsoft's repo, or you'll be able to work in a branch in Microsoft's repo.

  4. Make the relevant changes (and remember to save the changes!).

  5. Submit a pull request to the source repo.

    You'll have something like this configuration in a browser:

    The start of a pull request with fork on the right and target to the left.

Learn more at Quick edits to existing documents.

Get thorough

If you're going to contribute at a greater scale, for example as part of a community project that adds code examples to a bunch of technical walkthroughs, you'll probably prefer to work locally on your device, based on a clone of your fork. Go to Install content authoring tools in the Microsoft Docs Contributor Guide for recommended tools and processes. The Microsoft team typically follows that workflow.

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

  1. Commit the changes to your fork 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.

    You'll have something like this configuration in a browser:

    The start of a pull request with fork on the right and target to the left.

Tip

If you want to request brand new content, as opposed to contributing, 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 FieldTopicTextExtractor 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