Skip to content

plugin-publishing.md

Latest commit

 

History

History
66 lines (42 loc) · 5.26 KB

plugin-publishing.md

File metadata and controls

66 lines (42 loc) · 5.26 KB
Raw

Plugin documentation publishing

This area covers CMDS Eagle, CMDS Achmage, CMDS Share, and CMDS Zotero. Other gallery entries remain separate and are not removed by this workflow.

Sources and generated files

Layer Source Purpose
Editorial product data catalog/plugins.json Bilingual product summaries, requirements, source version, and verified release status
Manual masters The owner's Obsidian vault, 70. Outputs/74. Projects/CMDSPACE Plugins/ Authoritative Korean and English guide content
Repository copies Each plugin repository's docs/guide.md and docs/guide.ko.md Reviewed public Markdown
Web copies plugins/<slug>/guide.ko.md, guide.en.md Identical public Markdown for download
Rendered pages plugins/<slug>/index.html Static HTML generated by Marked, not a second manuscript
Navigation catalog catalog/apps.yaml → data/apps.json App cards linking to the documentation with docs_url

The manuals record source-version scope. A manifest version, a local Git tag, a GitHub release, Community-directory acceptance, and a verified live workflow are different facts. Zotero remains in development. A new release needs a new review, not just a changed badge.

Build locally

Install the pinned dependencies with npm ci. Set VAULT_ROOT and DEV_ROOT to the real directories on your machine; these values are never embedded in public pages.

node scripts/sync-plugin-docs.mjs --vault-root "$VAULT_ROOT" --repo-root "$DEV_ROOT"
node scripts/sync-plugin-docs.mjs --vault-root "$VAULT_ROOT" --repo-root "$DEV_ROOT" --write
npm run build:plugins
python3 scripts/check-plugins.py --out "$SCRATCH/plugin-web-checks"

Sync reads exactly eight date-prefixed master files, validates the required metadata, removes their frontmatter, and rejects private navigation or credentials. Documented Obsidian syntax inside code is preserved. Existing repository copies must already match the reviewed master; divergence stops the export rather than silently overwriting another author's edits.

The renderer supports Markdown tables and nested lists, creates heading anchors and a table of contents, escapes raw HTML, and rejects unsafe URL schemes. The browser progressively adds glossary hints, table scrolling, copy buttons, language/theme persistence, and section tracking. Core guide text is readable without JavaScript.

Updating navigation without scanning unrelated projects

scan.mjs preserves docs_url when regenerating the catalog. A full scan also rewrites candidate reports and queries external services. Do not run it merely to build these guides. Keep any pre-existing catalog changes and review only the named plugin entries for a documentation-only update.

Public upload boundary

Do not deploy the working directory wholesale: it includes private candidate-discovery reports and local operations sources. Build a new public staging directory:

node scripts/stage-public.mjs --out "$PUBLIC_STAGE"

The stage contains only the homepage, public app manifest, plugin pages/guides, selected brand assets and Vercel configuration. Private repository links detected in the catalog are removed from this derivative; the original local candidate records are untouched. No candidates, scanner sources, vault originals, .git, or local configuration are copied.

Before any deployment:

  1. Inspect the complete stage, compare hashes to the verified build, and review the manifest's links.
  2. Confirm the Vercel project is the existing apps-cmdspace project, not a new project inferred from the staging-directory name.
  3. Obtain approval for the exact public changes and deployment target.
  4. Deploy only the reviewed stage, then check the real URLs, language variants, Markdown downloads and share images.

Staging does not publish, commit, push, or certify a plugin. Public approval is separate from runtime testing. Repository README updates, GitHub descriptions/topics and profile-table changes also require their own approved external-write scope.

Seminar separation

Permanent product guides live under apps.cmdspace.work/plugins/. The dated September 14 seminar belongs under labs.cmdspace.work/achmage-seminar-0914/. Its existing registration-analysis snapshot must stay intact. Public slides must not contain speaker notes, participant data or private vault paths. Use a separate clean derivative for posting.

Verification scope

check-plugins.py tests the actual generated website: 400/1440px × KO/EN × light/dark, local links and anchors, duplicate IDs, theme/language switching, keyboard glossary, direct English heading links, JavaScript-free reading and blocked-storage fallback. It does not establish live plugin execution, external repository availability, Community registration, or production deployment.

Git-integrated Vercel builds

The Apps project also has a live Git integration. vercel.json runs npm run build:public and serves only the generated public/ directory, applying the same allowlist to automatic deployments. The committed HTML guides are already built; this step needs no vault access. The source working tree and candidate reports are not served. A direct upload stage removes those source-build settings because it contains only ready-to-serve files, not npm build sources.