feat(docs-sync): introduce Plugins category#223
Merged
Conversation
Fold loading-state rendering into BladeHeader and BladeToolbar instead of swapping in separate skeleton components. The header now renders skeleton placeholders only for icon/title/subtitle while keeping close, expand and collapse buttons operational, so a long-loading blade can always be dismissed. The toolbar renders inline skeleton buttons/widgets when loading and is omitted on mobile, matching previous behavior. Removes obsolete BladeHeaderSkeleton and BladeToolbarSkeleton components along with their tests; corresponding loading coverage is added to BladeHeader.test.ts and BladeToolbar.test.ts.
New @vc-shell/docs-sync package providing three commands: - sync: parses *.docs.md files (frontmatter via zod), runs them through a transformer pipeline (strip-internal blocks, expand ::storybook directives into iframe HTML, rewrite cross-doc links, prepend AUTO-GENERATED header), writes atomically into vc-docs target tree, emits .pages files for awesome-pages nav, detects orphaned auto-generated files, and produces a markdown sync report. - lint: validates *.docs.md against the docs template with six rules (frontmatter required, storybook id valid, image size limit, vue-block presence, material-feature warning, mermaid syntax). - screenshot: Playwright-based capture wrapping style-guide defaults (1280x800 viewport, 2x density, headless chromium); supports both direct URLs and Storybook story IDs. 47 unit + integration tests, TDD for every module. End-to-end integration test validates fixture sync, image copy, and internal-file skip semantics.
- docs-lint.yml: runs `docs-sync lint` on every PR that touches *.docs.md / *.stories.ts / cli/docs-sync. Catches frontmatter and template issues before merge. - sync-docs.yml: on every published vc-shell release (non-prerelease), checks out vc-docs, runs the sync, and opens an auto-PR labeled `auto-generated` from a bot account. Requires repo secret VC_DOCS_BOT_TOKEN with write access to vc-docs. The companion `protect-generated.yml` workflow lives in vc-docs (kept on the docs/protect-generated feature branch there) and blocks any non-bot PR from editing files marked AUTO-GENERATED FROM vc-shell.
- package.json: add yarn docs:sync, docs:lint, docs:screenshot shortcuts that proxy into the cli/docs-sync workspace. - CLAUDE.md: document the docs sync workflow under a new Documentation section so future sessions discover the right command surface.
…guide Replaces the stub README with comprehensive documentation covering: - the *.docs.md frontmatter contract and category/group taxonomy - routing rules and source → target path mapping - internal blocks, ::storybook directive, image co-location, link rewriting - the AUTO-GENERATED marker and protect-generated CI guarantee - detailed sync/lint/screenshot command reference - all six lint rules with severity and behavior - screenshot style guide + Playwright capture workflow - CI integration (docs-lint, sync-docs, protect-generated workflows) - versioning model under mike + Phase 1 banner / Phase 2 versioned Storybook - project layout, stack, contributor guide for new rules and transformers - Phase 0 editorial-pass context, status table, troubleshooting Q&A
Adds frontmatter (title/category/group/slug), Storybook embed directives, internal-only blocks for contributor-facing notes, and material admonitions for long pages on five representative *.docs.md sources used to e2e-test the docs-sync pipeline: - vc-button.docs.md (components/misc) + 4 ::storybook embeds - vc-data-table.docs.md (components/data-display) + 3 embeds - useBlade.docs.md (composables/blade-navigation) - useDataTableSort.docs.md (composables/data) - services.docs.md (concepts/services) All five pass yarn docs:lint with zero errors. Verified end-to-end locally against a real vc-docs checkout: yarn docs:sync produces the expected target paths, embeds render iframes correctly, admonitions get material-styled, internal blocks are stripped, and frontmatter disappears from the rendered HTML.
Awesome-pages, when a .pages file declares `nav:` with bare filename
entries (`- vc-button.md`), uses the filename as the displayed title
with smart-casing — `vc-button.md` becomes "Vc button" in the rendered
left sidebar. The page's own H1 ("# VcButton") is NOT consulted in
this code path.
Switch the writer to emit `Title: filename.md` pairs in the .pages
nav, where Title comes from the source frontmatter. Result: nav now
shows "VcButton", "VcDataTable", "useBlade", "useDataTableSort"
correctly. Existing alphabetical ordering preserved.
Test updated to assert the new line format.
…mplate
All framework documentation source files brought up to docs-sync template
standard:
- Frontmatter (title, category, group, optional slug) on every public file
- 24 framework-internal files marked `internal: true` and excluded from
public sync (shell/{_internal,auth,components,dashboard}, useUserManagement,
notification-template internals)
- Storybook embeds added to every UI component (atoms/molecules/organisms);
story IDs validated against live https://vc-shell-storybook.govirto.com/index.json
- Contributor-only architecture sections wrapped in <!-- internal:start --> /
<!-- internal:end --> markers
- Material admonitions (!!! note/warning/tip) added on pages >200 lines
to satisfy the material-feature-warn rule
Lint passes with 0 errors and 2 advisory warnings. yarn docs:sync produces
127 changes / 24 skipped / 0 errors against ../vc-docs.
Phase 0 covers the editorial pass spec'd in
docs/superpowers/specs/2026-04-28-vc-shell-docs-sync-design.md and unblocks
the auto-sync workflow on every framework release.
Add plugins/ as a top-level docs category alongside components/ and composables/ — adopting the Quasar/Vue convention where Plugins are a first-class section rather than a sub-category of "concepts". Frame- work-source plugin docs (AI Agent, SignalR, Validation, etc.) move out of concepts/, leaving concepts/ for hand-written narrative content. docs-sync changes (cli/docs-sync): - New category 'plugins' (group: root only) → emits plugins/<slug>.md - New frontmatter flag 'placement: index' → emits at <category>/<group>/index.md instead of <slug>.md, used for group landing pages - Writer emits flat plugins/.pages with explicit titles, alphabetical - Per-group .pages prepends 'Overview: index.md' when a group has an index page - Lock concepts/ and reference/cli in MANUAL_ONLY_FOLDERS so docs-sync never overwrites hand-curated content there - 7 new unit tests, 55 total passing Framework source updates (framework/core): - 9 plugin *.docs.md sources re-categorized from concepts to plugins: ai-agent, extension-points, global-error-handler, i18n, modularity, notifications, permissions, signalr, validation - permissions: slug 'permissions-plugin' → 'permissions', title and H1 'Permissions Plugin' → 'Permissions' (section name now disambiguates) - services.docs.md: re-categorized to composables with placement: index, positioning it as composables/services/index.md (the group landing page) When the next vc-shell release triggers sync-docs.yml, vc-docs receives 9 new plugins/*.md files, a new composables/services/index.md, and the auto-generated .pages files for those sections. Manual cleanup of stale concepts/* orphans is handled in companion PRs to vc-docs.
|
📦 Preview published for commit Install the preview with dist-tag: npm install @vc-shell/framework@pr-223Or pin to the exact commit: npm install @vc-shell/framework@2.0.3-pr223.78fd53ePublished packages (dist-tag
|
This was referenced May 12, 2026
- Bumped package version in package.json from 0.1.0 to 2.0.3. - Introduced a new sync report file (sync-report.md) detailing the sync results, including counts of created, updated, unchanged, and skipped documents.
2 tasks
maksimzinchuk
added a commit
that referenced
this pull request
May 12, 2026
## Summary Hotfix on top of #223 / #224. The new workflow_dispatch trigger fails immediately with `Input required and not supplied: token` because the `VC_DOCS_BOT_TOKEN` secret was never provisioned in this repo. Switch to the org-wide `REPO_TOKEN` secret that is already used by `release.yml` and `storybook-ci.yml` in this repo, and by `deploy.yml` in vc-docs — one secret to rotate instead of two. ## What changes - `.github/workflows/sync-docs.yml`: - `token: \${{ secrets.VC_DOCS_BOT_TOKEN }}` → `token: \${{ secrets.REPO_TOKEN }}` (both checkout step and `GH_TOKEN` env on the PR step) - Update top-of-file comment to reference REPO_TOKEN ## Behavior No behavioral change. Same workflow, same triggers, same auto-PR shape (with `auto-generated` label). Only the underlying token identity differs. `REPO_TOKEN` must have `contents:write` and `pull-requests:write` on `VirtoCommerce/vc-docs` — same permissions docs-deploy already exercises in vc-docs. ## Test plan - [ ] After merge: Actions → sync-docs → Run workflow → `target_branch: docs/vc-shell-integration` → Run - [ ] Verify auto-PR opens against the specified branch with the `auto-generated` label, no token error
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.
Summary
Introduce a top-level
plugins/documentation category in the docs-sync pipeline, alongside the existingcomponents/andcomposables/. Plugin reference docs (AI Agent, SignalR, Validation, Notifications, etc.) move fromconcepts/to a peer section.concepts/becomes reserved for hand-written narrative content. Adopts the Quasar/Vue convention where Plugins are a first-class section.What changes
docs-sync (cli/docs-sync)
plugins(top-level peer of components/composables, flat —group: rootonly)placement: index— emits a file at<category>/<group>/index.mdinstead of<category>/<group>/<slug>.md. Used for group landing pages.plugins/.pageswith explicit titles, alphabetical.pagesprependsOverview: index.mdwhen a group has an index pageconcepts/andreference/clilocked inMANUAL_ONLY_FOLDERS— docs-sync no longer overwrites their hand-curated contentFramework docs sources (framework/core)
.docs.mdfiles re-categorized fromcategory: conceptstocategory: plugins: ai-agent, extension-points, global-error-handler, i18n, modularity, notifications, permissions, signalr, validationcore/plugins/permissions/permissions.docs.md: slugpermissions-plugin→permissions, title and H1Permissions Plugin→Permissions(the section name now disambiguates)core/services/services.docs.md: re-categorized tocomposableswithplacement: indexfor theservicesgroup — positions it as the group landing pageAfter this PR lands and a release is cut
The
sync-docs.ymlworkflow auto-creates a PR in VirtoCommerce/vc-docs with:plugins/*.mdfilesplugins/.pages(auto-generated)composables/services/index.md(Services overview)composables/services/.pageswithOverview: index.mdfirstCompanion PRs in vc-docs cover the manual cleanup that docs-sync does not handle (orphan deletions, narrative rename, manual
.pagesupdates).Test plan
yarn workspace @vc-shell/docs-sync test— 55 tests passyarn build:cli— TypeScript cleanyarn docs:sync --dry-run --target ../vc-docs— 10 creates, 10 orphans, 0 errors