Generate beautiful documentation with ALDoc

Microsoft just released a new exciting tool for generating technical reference documentation of any app. In this video, I get the tool working on one of my apps. Check it out:

https://youtu.be/MNOEb5W1KQg

In this video, Erik walks through the new ALDoc tool that Microsoft introduced for Business Central — a command-line utility that generates beautiful technical reference documentation for your AL apps. He demonstrates the full process from installation through to serving a documentation website locally, using his SharePoint Connector app as an example.

What is ALDoc?

If you attended Directions EMEA, you may have seen Microsoft showcasing a new tool to generate technical documentation for Business Central apps. The idea is that you can see what objects exist in an app, what functions are available, their parameters, return values, and any XML documentation comments you’ve written — all rendered as a clean, browsable website.

You can already see this in action on learn.microsoft.com, where you can look up things like the Base64 codeunit, see its functions, parameters, and documentation. That’s built with ALDoc, and now we have access to the tool ourselves.

Prerequisites and Setup

AL Language Extension v12 (Pre-release)

ALDoc ships as part of the AL Language extension version 12, which at the time of recording was the pre-release version targeting Business Central 2023 Wave 2 (October release). To get it, you need to switch to the pre-release version of the AL Language extension in VS Code.

The ALDoc executable lives alongside the AL compiler. You can find it at:

~/.vscode/extensions/ms-dynamics-smb.al-<version>/bin/

In that bin folder, you’ll see:

  • alc — the AL compiler
  • altpgen — the generator for CRM tables
  • aldoc — the new documentation tool

Running aldoc without arguments shows the available verbs: init, build, refresh, help, and version.

Installing .NET and DocFX

ALDoc is only half of the equation. It generates input for another Microsoft tool called DocFX, which is the documentation rendering engine used across Microsoft for generating sites like learn.microsoft.com.

You need .NET installed on your machine. Erik is running .NET 7, which works fine. You can check with:

dotnet --version

Next, install DocFX. Here’s an important gotcha — the default install command will give you version 2.71, which does not work with ALDoc. You must specifically install version 2.70:

dotnet tool install docfx --version 2.70 -g

If you just run dotnet tool update -g docfx, you’ll get 2.71, and things will break in hard-to-debug ways.

The Two-Step Documentation Process

Generating documentation is a two-step process:

  1. ALDoc generates YAML files and scaffolding from your .app file
  2. DocFX converts those YAML files into a browsable HTML website

Step 1: ALDoc Init

First, initialize the documentation structure by telling ALDoc where to put output and which app file(s) to document:

aldoc init -o ./output -t path/to/your-app.app

The -o flag specifies the output folder, and -t points to the app file you want to document. You can specify multiple app files for cross-referencing.

After running init, you’ll find in the output folder:

  • A docfx.json configuration file
  • An index.md markdown file (the landing page)
  • A template folder with the Business Central-specific DocFX template
  • A table of contents file

Step 2: ALDoc Build

Next, run the build to generate the actual YAML documentation files from your app:

aldoc build -o ./output -s path/to/your-app.app

Note that the flag changes from -t to -s for the build step. This creates a reference folder containing YAML files for every codeunit, table, page, report, and other objects in your app.

You may see warnings about unresolved references — for example, if your code references TempBlob from the System Application but you haven’t included that app file for cross-referencing. Erik notes it would be great if ALDoc could link to the official Microsoft Learn documentation instead of requiring you to include the System Application in your build.

Step 3: DocFX Build

Now hand the generated files over to DocFX to build the HTML website:

docfx build ./output/docfx.json

This creates an _site folder with a complete static website.

Step 4: Serve the Website

DocFX can also act as a web server to preview your documentation:

docfx serve ./output/_site

By default, this serves on localhost:8080. You can use the -p flag to specify a different port if needed.

The Complete Script

Erik created a batch script to automate the full process:

rem Clean up previous output
rmdir /s /q output
mkdir output

rem Step 1: Initialize ALDoc structure
aldoc init -o ./output -t path/to/sharepoint-connector.app

rem Step 2: Build documentation from app file
aldoc build -o ./output -s path/to/sharepoint-connector.app

rem Step 3: Build the HTML site with DocFX
docfx build ./output/docfx.json

rem Step 4: Serve the documentation locally
docfx serve ./output/_site

The script starts by cleaning up any previous output so you can run it repeatedly during development.

Exploring the Generated Documentation

The generated site includes several nice features:

  • Navigation — A sidebar organized by modules (based on your folder structure in the AL project)
  • Search — A search function to find objects and methods
  • Object details — Tables show their fields and keys, pages show their layout, codeunits show their methods
  • Cross-references — Links between related objects (e.g., “See also” links on table documentation)
  • Dark/Light mode — Built-in theme switching
  • Landing page — Customizable via the index.md file

XML Documentation Comments

The real power comes when you add XML documentation comments to your AL code. Erik demonstrates this by adding documentation to a DeleteFolder function in his SharePoint Connector codeunit:

/// <summary>
/// Delete a folder in SharePoint.
/// </summary>
/// <remarks>
/// There is no user confirmation before the folder is deleted.
/// </remarks>
/// <param name="FolderPath">The path of the folder to delete.</param>
/// <returns>True if the folder was successfully deleted.</returns>
procedure DeleteFolder(FolderPath: Text): Boolean

After adding the documentation, you need to rebuild the app file first, then re-run the ALDoc/DocFX process. Erik caught himself on camera forgetting this step — a good reminder that ALDoc works from the compiled .app file, not directly from source code.

Once rebuilt, the documentation site shows the summary, remarks, parameters, and return value beautifully formatted on the method’s page.

Observations and Rough Edges

Erik notes a few things that could be improved or need further investigation:

  • The menu structure uses object name suffixes (like “EFQ”) inconsistently — sometimes showing the full object name, sometimes just the folder name
  • The search functionality feels incomplete in this pre-release version
  • It would be valuable if cross-references to System Application or Base Application objects could link to the official Microsoft Learn documentation instead of requiring those apps to be included
  • The template is customizable — the template folder contains HTML, JSON, and other files that can be modified

Production Use and CI/CD Integration

Erik plans to integrate ALDoc into his CI/CD pipelines using AL Build. The idea is that whenever a new version of an app is built, the pipeline would automatically generate the documentation and deploy it to a web server. This means documentation stays in sync with the code automatically.

Why This Matters

Erik closes with an interesting observation about what makes this possible. Because Business Central has its own compiler with a complete syntax tree and rich metadata, building a tool like ALDoc is primarily a matter of reusing the existing compiler infrastructure rather than building everything from scratch. It’s a testament to the quality of the AL toolchain that Microsoft can add capabilities like this on top of what already exists.

Summary

ALDoc is a powerful addition to the Business Central developer toolkit. While still in pre-release and with some rough edges, it provides a straightforward way to generate professional reference documentation for your AL apps. The key takeaways are:

  • Install DocFX version 2.70 specifically (not 2.71)
  • The process is: aldoc init → aldoc build → docfx build → docfx serve
  • Add XML documentation comments to your AL code for richer documentation
  • Remember to rebuild your .app file before regenerating documentation
  • Plan to integrate this into your CI/CD pipeline for automatic documentation generation
  • The template is customizable if the default output doesn’t meet your needs
Picture of hougaard

hougaard