{"slug": "building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai", "title": "Building a Markdig Extension for DocFX: Remote Content Inclusion with AI Rewriting", "summary": "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.", "body_md": "If you've worked on a documentation platform at any scale, you've hit this\nproblem: content lives in multiple places, and you need to compose it into\na single, coherent site at build time.\nMaybe your API reference is generated from code. Maybe your troubleshooting\nguides live in a separate service. Maybe different teams own different sections,\nand you need to pull them together into one DocFX site without copy-pasting\ncontent that goes stale the moment it's duplicated.\nDocFX — Microsoft's open-source documentation\ngenerator — is excellent at building static documentation from local markdown\nfiles. But it doesn't natively support fetching and inlining content from remote\nsources at build time.\nI needed exactly that capability. So I built it.\ndocfx-remote-include is\na standalone Markdig extension and CLI tool\nthat adds remote content inclusion to DocFX.\nIt's not a fork of DocFX. It hooks into DocFX's public BuildOptions.ConfigureMarkdig\nextension point, so it tracks upstream releases as a regular NuGet dependency. When\nDocFX updates, your remote include capability doesn't break.\nIn any markdown file processed by DocFX, you can write:\nSome local content.\n[!remoteinclude[Welcome](path/to/snippet.md)]\nMore local content.\nAt build time, the extension fetches {baseUrl}/path/to/snippet.md\nvia HTTP,\nparses the response as markdown, and inlines the result. It works in two modes:\n<p>\ntags).Here's where it gets interesting. You can optionally add a rewrite hint:\n[!remoteinclude[Install](snippets/install.md \"match this page's tone and tense\")]\nWhen a hint is provided, the fetched content is passed through a pluggable\nIRewriteService\n— backed by any LLM you choose (Azure OpenAI, local models,\nanything) — which adapts the content to match the surrounding page's voice\nand style.\nWithout a hint, the content is inlined verbatim. The AI capability is entirely\nopt-in and has zero vendor lock-in.\nForking DocFX would mean maintaining a parallel codebase and falling behind on\nupstream improvements. Instead, docfx-remote-include\nuses the public\nConfigureMarkdig\nseam that DocFX exposes:\nawait Docset.Build(\"docs/docfx.json\", new BuildOptions\n{\nConfigureMarkdig = pipeline => pipeline.UseRemoteInclude(client, options),\n});\nThis means:\nConfigureMarkdig\nEnterprise documentation often lives behind authentication. The extension\nsupports multiple auth modes out of the box:\nAll credentials are read from environment variables or host callbacks — never\nfrom config files committed to source control.\nWhen you're pulling remote content into a build pipeline, things can go wrong:\nAsyncLocal\nsource stack prevents infinite recursion\nwhen remote content includes other remote content. Max depth defaults to 8.--allow-missing\nto render a visible error placeholder instead.# Add the NuGet source (one-time)\ndotnet nuget add source \"https://nuget.pkg.github.com/saipramod/index.json\" \\\n--name \"docfx-tools\" --username YOUR_GITHUB_USERNAME --password YOUR_GITHUB_PAT\n# Install the tool\ndotnet tool install -g Docfx.RemoteInclude.Cli --source \"docfx-tools\"\n# Build your docs\ndocfx-ri build docs/docfx.json\nCreate remoteinclude.json\nnext to your docfx.json\n:\n{\n\"baseUrl\": \"https://your-content-service.com/\",\n\"allowMissing\": false,\n\"urlTemplate\": \"api/content/GetFile?path={source}\",\n\"auth\": {\n\"mode\": \"managedIdentity\",\n\"scope\": \"api://your-app-id/.default\"\n},\n\"ai\": {\n\"endpoint\": \"https://your-aoai.openai.azure.com/\",\n\"deployment\": \"gpt-4o-mini\",\n\"contextStrategy\": \"section\"\n}\n}\nFor full control, use the library directly:\nusing Docfx;\nusing Docfx.RemoteInclude;\nusing var client = new HttpRemoteContentClient(\nbaseUri: new Uri(\"https://your-content-service.com/\"),\nauthHandler: async (request, ct) =>\n{\nrequest.Headers.Authorization =\nnew(\"Bearer\", await GetJwtAsync(ct));\n});\nawait Docset.Build(\"docs/docfx.json\", new BuildOptions\n{\nConfigureMarkdig = pipeline => pipeline.UseRemoteInclude(client,\nnew RemoteIncludeOptions\n{\nRewriteService = myRewriter, // optional\n}),\n});\nImplement IRemoteContentClient\nfor non-HTTP sources (file systems, databases,\nsigned URLs). Implement IRewriteService\nto plug in any LLM.\nDocumentation platforms at scale need to compose content from multiple\nauthoritative sources. Copy-pasting creates drift. Git submodules add complexity.\nCustom build scripts are fragile.\ndocfx-remote-include\nsolves this with a clean, declarative syntax that works\nwithin DocFX's existing pipeline. The optional AI rewriting capability means\ncontent from different sources can read as if it was written for the page it\nappears on.\nThe project is MIT-licensed, open source, and accepting contributions.\nGitHub: github.com/saipramod/docfx-remote-include\nSai Pramod Upadhyayula is a Senior Software Engineer at Microsoft, where he\nworks on AI-powered enterprise knowledge platforms. He co-authored \"AutoTSG:\nLearning and Synthesis for Incident Troubleshooting\" (ESEC/FSE 2022) and\ncontributes to the DocFX open-source ecosystem.", "url": "https://wpnews.pro/news/building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai", "canonical_source": "https://dev.to/saipramod/building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai-rewriting-hb7", "published_at": "2026-05-22 22:35:09+00:00", "updated_at": "2026-05-22 23:03:13.524718+00:00", "lang": "en", "topics": ["developer-tools", "open-source"], "entities": ["DocFX", "Microsoft", "Markdig"], "alternates": {"html": "https://wpnews.pro/news/building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai", "markdown": "https://wpnews.pro/news/building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai.md", "text": "https://wpnews.pro/news/building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai.txt", "jsonld": "https://wpnews.pro/news/building-a-markdig-extension-for-docfx-remote-content-inclusion-with-ai.jsonld"}}