Improve experience of docify scaffold and the eventual static website deployment of multiple scaffolded architectures.

[LeighFinegold]

Background

As discussed on #2039 as part of the demo of the create website mode pull/2061, post scaffolding, deployment becomes a bit fiddly for the end user as they still require a reference to the architecture file which can only be found in the front-matter of scaffolded files.

In addition, if multiple architecture files had been scaffolded, one may want to deploy one website from those generated files, rather than deploy distinct websites per architecture.

Per suggestion from @rocketstack-matt, we could look to split the current "Create Website" workflow into two distinct phases:

1. Scaffold phase: Generate content pages and an index.json manifest describing the site structure
2. Deploy phase: Generate Docusaurus configuration files (sidebars.js, package.json, docusaurus.config.js) from the manifest leveraging the index.json file (this can be altered by the user

This allows users to customize the site structure before generating the deployment configuration.

Problem Statement

Currently, docify --scaffold generates both:

• Content pages (docs/nodes/*.md, docs/relationships/*.md)
• Docusaurus configuration (package.json, sidebars.js, docusaurus.config.js)

This creates friction when users want to:

• Customize which pages appear in the sidebar
• Reorder navigation items
• Add custom pages not generated from the architecture
• Review the site structure before committing to a deployment configuration

Current Workflow

calm docify --scaffold
    │
    └── Generates everything at once:
        ├── docs/
        │   ├── index.md
        │   ├── nodes/*.md
        │   └── relationships/*.md
        ├── package.json
        ├── sidebars.js
        └── docusaurus.config.js

Proposed Workflow

calm docify --scaffold
    │
    └── Phase 1: Generate content + manifest
        ├── docs/
        │   ├── index.md
        │   ├── nodes/*.md
        │   └── relationships/*.md
        └── index.json          (NEW: site structure manifest)

calm docify --deploy (or new command)
    │
    └── Phase 2: Read manifest, generate deployment config
        ├── package.json
        ├── sidebars.js
        └── docusaurus.config.js

Example index.json Manifest

{
  "title": "E-Commerce System",
  "version": "1.0.0",
  "generatedFrom": "system.json",
  "pages": [
    {
      "id": "index",
      "path": "docs/index.md",
      "label": "Overview",
      "sidebar": true,
      "order": 0
    },
    {
      "id": "nodes",
      "label": "Nodes",
      "sidebar": true,
      "order": 1,
      "children": [
        { "id": "ecommerce-system", "path": "docs/nodes/ecommerce-system.md", "label": "E-Commerce System" },
        { "id": "payment-service", "path": "docs/nodes/payment-service.md", "label": "Payment Service" },
        { "id": "inventory-service", "path": "docs/nodes/inventory-service.md", "label": "Inventory Service" }
      ]
    },
    {
      "id": "relationships",
      "label": "Relationships",
      "sidebar": true,
      "order": 2,
      "children": [
        { "id": "sys-composition", "path": "docs/relationships/sys-composition.md", "label": "System Composition" }
      ]
    }
  ]
}

User Impact

• Users can edit index.json to customize navigation before deploying
• Teams can version control the manifest separately from generated config
• Easier to add custom documentation pages to the sidebar
• Supports iterative workflows: regenerate content without losing sidebar customizations

Proposed Implementation

Phase 1: Update Scaffold Mode

1. Modify docify --scaffold to generate index.json instead of Docusaurus config
2. index.json describes all generated pages with metadata (path, label, order)
3. Content generation remains unchanged

Phase 2: New Deploy Command

1. Add calm docify --deploy or calm deploy command
2. Reads index.json from the output directory
3. Generates sidebars.js, package.json, docusaurus.config.js
4. Validates that referenced pages exist

VSCode Integration

1. Update "Create Website" command to run scaffold phase
2. Add new "Deploy Website" command for deploy phase
3. Consider a combined "Create and Deploy" option for simple workflows

Acceptance Criteria

• docify --scaffold generates index.json manifest
• index.json schema is documented
• New --deploy flag (or command) generates Docusaurus config from manifest
• Users can manually edit index.json before deploy
• VSCode extension updated with separate commands
• Backward compatibility: option to run both phases together

Open Questions

• Should --deploy be a flag on docify or a separate command?
• Should we support other static site generators in the future (manifest as abstraction)?
• How to handle manifest schema versioning?

Related Files

• shared/src/docify/docifier.ts
• shared/src/template/template-processor.ts
• shared/src/template/template-bundles/docusaurus/
• calm-plugins/vscode/src/commands/create-website/