Building a Markdig Extension for DocFX: Remote Content Inclusion with AI Rewriting

The article describes **docfx-remote-include**, a Markdig extension and CLI tool that adds remote content fetching and inlining capabilities to DocFX, Microsoft's open-source documentation generator. It allows users to include content from external sources at build time using a `[!remoteinclude]` syntax, with optional AI-powered rewriting via a pluggable `IRewriteService` to adapt the fetched content's tone and style. The tool integrates through DocFX's public `ConfigureMarkdig` extension point, supports various authentication modes, and includes safety features like recursion limits and error handling.

If you've worked on a documentation platform at any scale, you've hit this problem: content lives in multiple places, and you need to compose it into a single, coherent site at build time. Maybe your API reference is generated from code. Maybe your troubleshooting guides live in a separate service. Maybe different teams own different sections, and you need to pull them together into one DocFX site without copy-pasting content that goes stale the moment it's duplicated. DocFX — Microsoft's open-source documentation generator — is excellent at building static documentation from local markdown files. But it doesn't natively support fetching and inlining content from remote sources at build time. I needed exactly that capability. So I built it. docfx-remote-include is a standalone Markdig extension and CLI tool that adds remote content inclusion to DocFX. It's not a fork of DocFX. It hooks into DocFX's public BuildOptions.ConfigureMarkdig extension point, so it tracks upstream releases as a regular NuGet dependency. When DocFX updates, your remote include capability doesn't break. In any markdown file processed by DocFX, you can write: Some local content. remoteinclude Welcome path/to/snippet.md More local content. At build time, the extension fetches {baseUrl}/path/to/snippet.md via HTTP, parses the response as markdown, and inlines the result. It works in two modes: <p tags .Here's where it gets interesting. You can optionally add a rewrite hint: remoteinclude Install snippets/install.md "match this page's tone and tense" When a hint is provided, the fetched content is passed through a pluggable IRewriteService — backed by any LLM you choose Azure OpenAI, local models, anything — which adapts the content to match the surrounding page's voice and style. Without a hint, the content is inlined verbatim. The AI capability is entirely opt-in and has zero vendor lock-in. Forking DocFX would mean maintaining a parallel codebase and falling behind on upstream improvements. Instead, docfx-remote-include uses the public ConfigureMarkdig seam that DocFX exposes: await Docset.Build "docs/docfx.json", new BuildOptions { ConfigureMarkdig = pipeline = pipeline.UseRemoteInclude client, options , } ; This means: ConfigureMarkdig Enterprise documentation often lives behind authentication. The extension supports multiple auth modes out of the box: All credentials are read from environment variables or host callbacks — never from config files committed to source control. When you're pulling remote content into a build pipeline, things can go wrong: AsyncLocal source stack prevents infinite recursion when remote content includes other remote content. Max depth defaults to 8.--allow-missing to render a visible error placeholder instead. Add the NuGet source one-time dotnet nuget add source "https://nuget.pkg.github.com/saipramod/index.json" \ --name "docfx-tools" --username YOUR GITHUB USERNAME --password YOUR GITHUB PAT Install the tool dotnet tool install -g Docfx.RemoteInclude.Cli --source "docfx-tools" Build your docs docfx-ri build docs/docfx.json Create remoteinclude.json next to your docfx.json : { "baseUrl": "https://your-content-service.com/", "allowMissing": false, "urlTemplate": "api/content/GetFile?path={source}", "auth": { "mode": "managedIdentity", "scope": "api://your-app-id/.default" }, "ai": { "endpoint": "https://your-aoai.openai.azure.com/", "deployment": "gpt-4o-mini", "contextStrategy": "section" } } For full control, use the library directly: using Docfx; using Docfx.RemoteInclude; using var client = new HttpRemoteContentClient baseUri: new Uri "https://your-content-service.com/" , authHandler: async request, ct = { request.Headers.Authorization = new "Bearer", await GetJwtAsync ct ; } ; await Docset.Build "docs/docfx.json", new BuildOptions { ConfigureMarkdig = pipeline = pipeline.UseRemoteInclude client, new RemoteIncludeOptions { RewriteService = myRewriter, // optional } , } ; Implement IRemoteContentClient for non-HTTP sources file systems, databases, signed URLs . Implement IRewriteService to plug in any LLM. Documentation platforms at scale need to compose content from multiple authoritative sources. Copy-pasting creates drift. Git submodules add complexity. Custom build scripts are fragile. docfx-remote-include solves this with a clean, declarative syntax that works within DocFX's existing pipeline. The optional AI rewriting capability means content from different sources can read as if it was written for the page it appears on. The project is MIT-licensed, open source, and accepting contributions. GitHub: github.com/saipramod/docfx-remote-include Sai Pramod Upadhyayula is a Senior Software Engineer at Microsoft, where he works on AI-powered enterprise knowledge platforms. He co-authored "AutoTSG: Learning and Synthesis for Incident Troubleshooting" ESEC/FSE 2022 and contributes to the DocFX open-source ecosystem.