Register azure-cli-preview moniker for AzClips public preview (script-driven successor to #6153) - #6158
Draft
DanielMicrosoft wants to merge 4 commits into
Conversation
Adds the azure-cli-preview moniker to the docset config so content published under docs-ref-autogen/preview-version/latest can be built and rendered on Learn. The moniker itself is already registered in the docs.ms central store (Platform: bash, Family: Azure CLI, Product: Preview) with Live=false and Prerelease=true; it will remain hidden from the dropdown until content is staged and we request Live=true. Includes a minimal placeholder TOC.yml under docs-ref-autogen/preview-version/latest/ so docfx does not fail on the missing src folder. Actual content will land via subsequent PRs from the AzClips sync pipeline. Follows the folder-naming convention used by Latest-version/latest and LTS-version/latest per docs.ms guidance.
Runs AzClips's cli-export → CLI2Yaml 20260827.1.0 → SDP YAML pipeline against the current tip of Azure/azclips main, producing 20 reference files covering agent, config, deployment, disk, extension, group, identity, msgraph, profile, and vm verbs (plus TOC, reference-index, service-page). editLink values point at github.com/Azure/azclips/blob/main/… via the --sourceRepo and --editBranch options landed in CLI2Yaml PR 1213094. Content is a snapshot for review preview only; production content will be pushed by a subsequent AzClips sync pipeline. Moniker remains Live=false in the central store, so this content is invisible to customers until we request the flip.
Adds the missing azure-cli-preview entries to the 'groups' and 'versions' maps in docfx.json. Without these, the build system did not emit a ?view=azure-cli-preview parameter on preview-version URLs, causing 10 publish-url-conflict warnings against Latest/LTS files (e.g. both docs-ref-autogen/preview-version/latest/vm.yml and docs-ref-autogen/Latest-version/latest/vm.yml were claiming /cli/azure/vm). After this change, preview-version pages should publish to /cli/azure/<cmd>?view=azure-cli-preview, in line with the other monikers already registered.
The single preview-version/latest/service-page/azure-cli.yml page was emitting bare command names (agent, config, vm, ...) instead of az_-prefixed xrefs, producing 11 xref-not-found warnings against non-existent uids. It also only covered a catch-all 'azure-cli' service rather than the ~200 per-Azure-service pages that Latest/LTS carry. Removing it eliminates the warnings without any user-visible loss (reference-index and command TOC still render normally). Proper service-page generation will be re-enabled once the upstream azclips-side inputs (service_name.json + CLI2Yaml xref formatting) are fixed. Tracked in Azure/CLIPS as a follow-up sub-issue of MicrosoftDocs#588.
Contributor
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
Contributor
DanielMicrosoft
added a commit
to DanielMicrosoft/azure-docs-powershell
that referenced
this pull request
Sep 7, 2026
…e, feedback_system docs.ms Learn build succeeded for azps-100.0.0 content but produced no preview URLs (`Publish Files` empty, `% Files Skipped Publishing: 100.000%`). Comparing with MicrosoftDocs/azure-docs-cli#6158 (which does emit preview URLs) surfaced that `docfx.json` needed per-moniker entries the same way `mapping/monikerMapping.json` did. Mirrors the azps-16.3.0 shape (three content entries + one resource + versions dest + ms.date + feedback_system).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Registers the
azure-cli-previewmoniker for AzClips public preview and populatesdocs-ref-autogen/preview-version/latest/. Successor to #6153 — same tip content, now demonstrably reproducible from a script.What the AzClips team runs
Content commit was produced by the sync shim in Azure/azclips#798. Exact invocation from the AzClips repo root:
Config file the shim reads (
build/cli-docs-sync.config.json):{ "moniker": "azure-cli-preview", "versionFolder": "preview-version", "targetRepoPath": "../azure-docs-cli", "sourceRepoUrl": "https://github.com/Azure/azclips", "sourceBranch": "main", "exportProject": "tools/Help/Azclips.Cli.Export/Azclips.Cli.Export.csproj", "cli2yamlPackage": "CLI2Yaml", "cli2yamlFeed": "https://apidrop.pkgs.visualstudio.com/_packaging/ReferenceAutomation/nuget/v3/index.json" }Faithful reproduction — nothing changed vs. #6153
Running the shim against this branch reports
No changes to sync. The script-generated output is byte-identical to the hand-craftedc5bee8e4fdfrom #6153. This is a positive signal: the shim is a faithful implementation of what was manually authored during exploration.One-time setup commits (NOT reproducible by the shim yet)
The following config bits are moniker-onboarding one-timers. The shim does not author these — a docs.ms desk conversation created them. They're carried over from #6153:
bdde714.openpublishing.publish.config.json,docfx.json,docs-ref-autogen/preview-version/latest/TOC.yml— register the new moniker1767a77docfx.json— registerazure-cli-previewin docfx groups/versionseaecfd5service-page/azure-cli.yml(unresolvable xrefs; pending upstream)Open question for reviewers: are those three commits mergeable into
maintoday with zero consequences to the production docs experience? The moniker won't be linked from any live TOC unless docs.ms explicitly wires it up, so a merge of the config alone should be inert — but the AzClips team would like a docs.ms sanity-check before we optimize the process (e.g., splitting registration into its own tiny PR that lands independently of content refreshes).Content commit
c5bee8edocs-ref-autogen/preview-version/latest/**/*.yml— 11 top-level verb pages + subgroups +TOC.yml+reference-index.yml. Verified byte-identical to today's script output above.Blockers / caveats
CLI2Yaml--sourceRepo/--editBranch): resolved upstream inCLI2Yaml20260827.1.0— this PR uses that version,editLink:points athttps://github.com/Azure/azclips/blob/main/…as expected.-Pushmode + CI workflow both wait on this.service-page/cleanup (commiteaecfd5) is a temporary workaround — onceservice_name.jsonon the AzClips side maps verbs to real service pages, the shim will re-enable service-page output (-SkipServicePages:$false).Related