Repository navigation
docs: split the configuration reference out of the deployment guide - #2192
Merged
Merged
Conversation
The property reference was about 1150 of the deployment guide's 1300 lines, so the guide itself - getting started, the web UI, the upstream registry, HTTPS - was buried inside it, and the two serve different readers: one is followed once while setting a deployment up, the other is looked things up in afterwards. Content-preserving. Every property row and every line of prose is carried over untouched; the only rewrites are the three links that now cross a document boundary, and the sections of the reference move up a heading level now that they are no longer nested under one. Anchors derive from the heading text rather than its level, so every existing link still resolves, which was checked for all four - #oauth2, #upstream-registry, #upstream-registry-instance and #configuring-applicationyml, the last of these being the one the wiki overview points at. This also gives the planned CI check a file to own: the reference is where every property has to appear, while the guide stays prose. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
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.
Follows #2191. Splits the property reference out of
doc/deployment.mdintodoc/configuration.md.Why
The reference was about 1150 of the guide's 1300 lines, so the guide itself - getting started, the
web UI, the upstream registry, HTTPS - sat buried inside it. The two also serve different readers:
the guide is followed once while setting a deployment up, the reference is looked things up in
afterwards.
It also gives the planned CI check a file to own. The check compares the properties the code binds
against the ones documented, and
doc/configuration.mdis now unambiguously the file every propertyhas to appear in, while the guide stays prose.
Content-preserving
Every property row and every line of prose is carried across untouched. Verified rather than
asserted:
ovsx.*mentions are identical before and after, by diff.only the three cross-document link rewrites and the new intro and pointer lines.
The reference's sections move up a heading level (
###to##) now that they are no longer nestedunder
## Open VSX Configuration Properties. GitHub derives anchors from the heading text and notits level, so this changes no anchor.
Three links now cross a document boundary and were rewritten:
#oauth2configuration.md#oauth2#upstream-registryconfiguration.md#upstream-registry#upstream-registry-instancedeployment.md#upstream-registry-instanceAll four anchors in play were checked to resolve to exactly one heading in the right file, including
deployment.md#configuring-applicationyml, which is the one the wiki overview points at and whichstays put.
doc/deployment.mdkeeps a short## Configuration Propertiessection where the reference used tobe, linking to the new document, so the reading order still works.
README.mdnames both documents.Prepared with Claude Code.