Edit

Custom Help Toolkit: The HtmlFromRepoGenerator tool

  • Article
  • 5 minutes to read

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 custom help toolkit includes the HtmlFromRepoGenerator tool that gets Microsoft's content in MarkDown files and converts it to HTML files. You can then deploy the HTML files to a website.

The HtmlFromRepoGenerator tool is a wrapper around the DocFX component that Microsoft uses to generate HTML files for the learn.microsoft.com site. You can write your own scripts around this component, and maybe you already have that in place. If you don't, then the HtmlFromRepoGenerator tool can help you get started. Run the tool from a command prompt, use the examples as inspiration but remember to update the paths to suit your configuration.

Use the HtmlFromRepoGenerator tool to get MarkDown files and generate HTML files

HtmlFromRepoGenerator.exe provides functionality that supports the creation of custom Help based on source files from Microsoft. You can use HtmlFromRepoGenerator.exe to:

  • Clone a Microsoft documentation repository (repo)

  • Update links to files that are no longer in the clone

  • Update the ms.locale value to match the language options that are supported by Business Central

  • Generate HTML files that can be used for publishing to your own website

    The HTML files will be generated in the business-central\d365businesscentral subfolder, such as D:\BC\de-DE\business-central\d365businesscentral. This name of the subfolder is set in the docfx.json file in the en-US source repo. The tool applies the <meta name="robots" content="NOINDEX, NOFOLLOW"> tag to the HTML files, so if you use the tool to process your own content, you should remove these tags from your files but leave the tags in your version of Microsoft's content.

    Note

    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.

    The HtmlFromRepoGenerator tool generates files based on stylesheets and templates that are part of the tool.

  • Compare a localized Microsoft repo to the en-US repo to identify differences and update links accordingly

    The en-US repo includes files that are required for building the various localized versions, including the very important docfx.json file that sets the output location and certain metadata settings, some of which are important for the learn.microsoft.com site only. For more information, see Get content from the GitHub repos.

Syntax

Here is the syntax for HtmlFromRepoGenerator.exe:

HtmlFromRepoGenerator.exe --Out <path> [--DoNotClone <true|false>] [--Repo <URL>] [--RemoveGitFolder <true|false>] [--LogsDir <.\logs>] [--EnRepo <URL>] [--EnOut <path>] [--Lng <language code>] [--Rtl] [--?[--]]

The following table provides an explanation of the parameters:

Parameter Description
Out Specifies the folder where your existing clone is, or the folder to clone the repo to, such as D:\BC. If you run HtmlFromRepoGenerator to clone a repo, this folder must not already exist.
DoNotClone Set this parameter when you run the tool against a previously cloned repo.
Repo Specifies the repo URL. Optional if you run the tool based on a previously cloned repo. Microsoft documentation repo URL is https://github.com/MicrosoftDocs/dynamics365smb-docs for English (US).
Tag Specifies the tag corresponding to a release of the Business Central documentation. You can see a list of the releases at https://github.com/MicrosoftDocs/dynamics365smb-docs/releases.
RemoveGitFolder Specifies whether to remove the .git folder.
LogsDir Specifies the folder to save logs files to.

The following additional parameters are used when the tool is run against the localized Microsoft documentation repos:

Parameter Description
EnRepo Specifies the URL of the en-US repo. Optional if you run the tool on a previously cloned repo. The Microsoft documentation repo URL for English (US) is https://github.com/MicrosoftDocs/dynamics365smb-docs.
EnOut Specifies the folder where the en-US repo exists, or the folder to clone it to. This folder must not already exist if you run the tool based on a previously cloned repo.
Lng Specifies the language value to use for ms.locale metadata in the generated HTML files. If this parameter is not set, the tool uses en-US.
Rtl Set this parameter if the language uses right-to-left (RTL) formatting. Examples of RTL languages include Arabic and Hebrew.

Examples

Note

The Microsoft repos contain many files, so the process takes several minutes. If you run the tool against multiple localization repos, the process takes longer.

The following example clones the en-US repo and generates HTML files.

HtmlFromRepoGenerator.exe --out "D:\BC\en-US" --repo "https://github.com/MicrosoftDocs/dynamics365smb-docs" --LogsDir D:\BC\logs\en-US

The following example clones the en-US repo, checks out the repo at tag v16.5 (corresponding to the release "Microsoft Dynamics 365 Business Central v. 16.5 docs") and generates HTML files.

HtmlFromRepoGenerator.exe --out "D:\BC\en-US" --repo "https://github.com/MicrosoftDocs/dynamics365smb-docs" --tag v16.5 --LogsDir D:\BC\logs\en-US

The following example uses a previously cloned en-US repo and generates HTML files.

HtmlFromRepoGenerator.exe --out "D:\BC\en-US" --DoNotClone --LogsDir D:\BC\logs\en-US

Important

Do not run HtmlFromRepoGenerator.exe repeatedly on a previously-cloned repo. HtmlFromRepoGenerator modifies the links during processing, so running HtmlFromRepoGenerator more than once on the same content will result in incorrect links. If you want to rerun HtmlFromRepoGenerator, either use HtmlFromRepoGenerator to create a new clone of the repo, or revert all local changes to your existing clone.

Modifying the styling of the generated HTML files

The tool generates the HTML files based on a set of predefined templates that are defined in a resource that the tool relies on. In most cases, you can modify the stylesheets in the tool's styles output folder to tweak the appearance of your content.

For advanced scenarios, you can modify the predefined templates that the HtmlFromRepoGenerator tool uses. These templates determine fonts and other stylings for the website that the tool generates based on DocFx.exe. The templates are included in the SourceCode folder in the GitHub repo. The templates are in the SourceCode\HtmlFromRepoGenerator\HtmlFromRepoGenerator\HtmlFromRepoGenerator\Resources subfolder.

Note

If you modify the templates, you must rebuild HtmlFromRepoGenerator.exe using Visual Studio or similar.

For more information, see Introduction to DocFX Template System.

See also

Custom Help Toolkit