docs: Editor Integration guide + promote .yaml-workflow.yaml convention - #39
Conversation
…ention Adds a discoverable docs-site page (guide/editor-integration.md, in the nav) covering JSON Schema validation/autocomplete: the yaml-language-server modeline, VS Code + JetBrains setup, check-jsonschema, and the SchemaStore submission. Promotes a distinctive .yaml-workflow.yaml / .yml file-naming convention so the SchemaStore entry (SchemaStore/schemastore#6213) enables zero-config editor auto-detection without false positives. Updates schema/README.md to reflect the submitted status and cross-link the guide.
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page that consolidates editor/schema integration guidance and promotes the .yaml-workflow.yaml / .yaml-workflow.yml filename convention to enable SchemaStore-based zero-config autocomplete, updating existing schema docs and wiring the page into the MkDocs navigation.
Changes:
- Added a new “Editor Integration” guide documenting YAML Language Server modeline usage, VS Code/JetBrains schema mappings, and CI validation.
- Updated
schema/README.mdto recommend the.yaml-workflow.*suffix and reflect SchemaStore submission status. - Added the new guide page to the MkDocs “Guide” navigation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
schema/README.md |
Updates SchemaStore section and adds recommended filename convention + link to the new guide. |
mkdocs.yml |
Adds the new “Editor Integration” page to the Guide nav. |
docs/guide/editor-integration.md |
New guide consolidating editor setup, SchemaStore convention, and CLI validation instructions. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
Addressed both review comments in follow-up #40: local-schema modeline example now uses |
Follow-up to #39: local-schema modeline uses ../schema/... for the workflows/ layout; VS Code yaml.schemas example includes the .yaml-workflow.yml pattern.
Summary
Companion to the SchemaStore submission (SchemaStore/schemastore#6213). That entry uses a distinctive
*.yaml-workflow.yamlfileMatch(a genericworkflows/*.yamlpattern is rejected by SchemaStore as too broad) — so it only delivers zero-config editor autocomplete if we actually promote the convention. This PR does that, and makes the schema/editor story discoverable (it previously lived only inschema/README.md, which isn't in the docs nav).Changes
docs/guide/editor-integration.md(added to the Guide nav) — consolidates JSON Schema setup: theyaml-language-servermodeline (works for any filename), VS Code (Red Hat YAML) + JetBrains mappings,check-jsonschemafor CI, and the SchemaStore status..yaml-workflow.yaml/.ymlnaming convention for zero-config SchemaStore auto-detection, while making clear any filename still works via the modeline.schema/README.md— updates the SchemaStore section from "planned" to "submitted" (links the PR) and cross-links the new guide.Verification
mkdocs buildsucceeds; the new page renders and the nav entry resolves. (The 2 griffe warnings are pre-existing infile_tasks.py; docs CI uses non-strictmkdocs build.)src/changes — docs only.Note:
yaml-workflow initoutput filenames are intentionally left unchanged (renaming the bundled examples would break theirruncommands and tests); the convention is opt-in and documented.