Skip to main content

Docs-as-code workflow

note

Samples are genericized to mask proprietary information. Product images are mockups generated by Claude.

How the docs-as-code help site works, end to endContributors write in VS Code with a live local preview, or in the Azure DevOps browser editor with no setup. Everything is plain text in a Git repo: Markdown articles with YAML front matter, toc.yml navigation, docfx.json metadata, Swagger files for API reference, and a pipeline variables file. Changes go on a feature branch, through a pull request with review and a conflict check, and merge to main. The merge triggers a build pipeline that installs the shared theme package and runs npm, Gulp, and DocFX to turn Markdown and Swagger into HTML. The pipeline publishes to a development site on demand and to the production site on merge. Every published page has an Edit this page link and a feedback form, which send readers back into the browser editor so the loop starts again.WritePlain-text sourceReviewBuildPublishTriggersautomaticallyEdit this page opens the source file, so readers can become contributors and the loop starts againVS CodeClone, branch, editLive local previewBrowser editorAzure DevOpsNo setup neededdocs repo (Git)articles/**/*.mdMarkdown + YAML front mattertoc.ymlNavigation and orderingdocfx.jsonSite metadata and feature flagsrestapi/*.jsonSwagger specs for API referencebuilds/variables.ymlPipeline settingsFeature branchPull requestPeer review andconflict checkMerge to mainShared themeTemplates, CSS, JSBuild pipelinenpm → Gulp → DocFXMarkdown → HTMLSwagger → API refDev siteManual run, any branchProduction siteAuto on every mergeReadersEdit this page linkFeedback form
Content is treated like code: versioned, reviewed, built, and deployed automatically, with every published page linking back to its own source.

Automated deployment pipelines​

The automated pipelines behind every docs siteTwo triggers start a site's build pipeline: a merge to main runs automatically and always publishes to production, and a manual run lets the user pick any branch and check PROD, DEV, both, or neither. On the Azure Pipelines build agent, the shared publish.yaml template reads the site's variables file, installs Node, npm packages, the shared theme package, and the latest DocFX, optionally generates API metadata from .NET projects, builds the site with Gulp and DocFX, turning Markdown into HTML and Swagger into API reference, and stages the output as an artifact. The artifact deploys to production, to development, or is offered as a downloadable zip when no environment is checked. A separate theme pipeline publishes the shared theme as an npm package that every site installs on its next build. Benefits: zero manual deploy steps, one pipeline template, one theme change reaching every site, and per-task build logs.TriggersAzure Pipelines build agentBlob storageMerge to mainRuns automaticallyManual runAny branch, any targetbuilds/publish.yamlOne shared template, every site1Read settingsvariables.ymlURL + flags2InstallNode + npmTheme packageLatest DocFX3API metadata.NET projects→ API YAML4Build siteGulp + DocFXHTML pagesAPI reference5Stage artifact_site/Saved to runEvery runOnly when switched on in variables.ymlProductionOn merge, or PROD ✓DevelopmentWhen DEV ✓Downloadable zipWhen neither is ✓Shared theme pipelineInstalled by every siteon its next buildTheme update mergedOne changeTheme pipelineBuilds + versionsTheme npm packageSingle source of truthZero manual deploy stepsMerging to main is the releaseOne pipeline templateA new site edits one variables fileOne theme changeReaches every site on its next buildPer-task build logsFailures are pinpointed fast
Writers never touch a server: a merge or a two-click manual run handles the build, the theme, the API reference, and the deployment.

Contributions​

Article pages included an Edit this page link, which let contributors submit changes as pull requests. A Contributor reference link went to the Docs-as-Code Contributor Guide, which walked contributors through the steps.