RFC: Open CMS integration and content schema for Valaxy

[YunYouJun]

Motivation

Valaxy already has a strong Git-native content model: Markdown, frontmatter, site configuration, themes, and plugins live in the repository. However, an external content-management tool currently has to infer Valaxy conventions such as:

• where content collections live;
• which frontmatter fields are supported;
• which theme/site settings are safe to edit;
• how drafts, i18n, and previews work;
• how a change should be validated and serialized without losing unknown fields.

That makes every CMS integration Valaxy-specific and fragile. A small, open integration contract could let web CMSs, desktop apps, editor extensions, and other tools integrate without coupling Valaxy to one product or hosting provider.

Goals

• Define a versioned contract for discovering and editing Valaxy content.
• Describe content collections, frontmatter fields, editable theme/site settings, and supported capabilities.
• Preserve Git as the source of truth and keep generated files human-readable.
• Provide enough metadata for tools to generate forms, validate changes, and serialize them safely.
• Leave room for local preview and framework-aware preview integrations.
• Keep the contract open and vendor-neutral so multiple CMS implementations can use it.
• Avoid adding CMS-only runtime cost for Valaxy users who do not opt in.

Non-goals

• Building an admin UI directly into Valaxy core.
• Adding authentication, accounts, billing, Git providers, media storage, deployment, or a SaaS control plane to Valaxy.
• Requiring Yunle, CloudBase, GitHub, or any other specific vendor.
• Turning Valaxy into a database-backed or dynamic CMS.
• Standardizing every theme-specific setting in the first version.
• Replacing existing Markdown/frontmatter conventions.

Proposal

This is an initial shape for discussion, not a final API.

1. A versioned CMS manifest

A Valaxy site could optionally expose a serializable manifest:

interface ValaxyCMSManifest {
  version: 1
  collections: CMSCollection[]
  site?: CMSSchema
  theme?: CMSSchema
  capabilities?: {
    drafts?: boolean
    i18n?: boolean
    preview?: boolean
  }
}

The public API might eventually include a typed helper such as defineValaxyCMS(), but the resulting contract should be serializable and consumable without importing a CMS implementation.

2. Content collection schema

Each collection could describe:

• its source path and file format;
• the body field;
• frontmatter fields and validation rules;
• filename/slug behavior;
• draft and locale conventions;
• default values and editor-facing labels.

A minimal field vocabulary might cover text, number, boolean, date/datetime, image, select, list, object, and relation fields. The schema should be extensible, and tools must preserve unknown frontmatter fields to avoid destructive round trips.

Illustrative example:

defineValaxyCMS({
  version: 1,
  collections: [
    {
      name: 'posts',
      label: 'Posts',
      path: 'pages/posts',
      format: 'markdown',
      fields: {
        title: { type: 'text', required: true },
        date: { type: 'datetime' },
        tags: { type: 'list', item: { type: 'text' } },
        cover: { type: 'image' },
      },
    },
  ],
})

3. Theme and site configuration schema

Valaxy core and theme authors could optionally declare which settings are editable, including labels, defaults, validation, and documentation. The CMS metadata should remain optional and should not pull editor, authentication, or cloud-service dependencies into normal Valaxy builds.

Theme schemas should be able to extend a shared base schema while keeping theme-specific fields namespaced and versioned.

4. Discovery and serialization

External tools need a stable way to discover the manifest and write changes back safely. Possible approaches include:

• a committed JSON/JSON Schema manifest;
• a conventional valaxy.cms.ts file plus a Valaxy CLI command that emits JSON;
• metadata exported by Valaxy and theme packages;
• a hybrid approach with a serializable base manifest and optional local resolution.

Whichever approach is chosen should define:

• schema/version negotiation;
• Markdown and frontmatter serialization behavior;
• preservation of unknown data;
• conflict detection based on the source commit/blob;
• safe handling of TypeScript config that cannot be losslessly rewritten.

Remote services should not need to execute arbitrary repository code merely to discover a schema.

5. Preview capability

The contract may advertise preview support without prescribing a hosting provider. A first version could standardize preview inputs (content path, draft content, locale, base commit) and let adapters decide whether preview runs locally, in CI, or through an external service.

6. Adapter model

Valaxy would own only the open contract. Integrations would live independently:

VS Code / desktop / web CMS / future tools
                    |
           Valaxy CMS contract
                    |
             Valaxy project

A staged rollout could start with convention-based adapters outside Valaxy, validate real use cases, and only then stabilize the smallest useful contract in Valaxy core.

Open Questions

1. Should the canonical schema be JSON Schema, a Valaxy-specific serializable format, a typed TypeScript builder, or a combination?
2. Where should site-level schema live: valaxy.config.ts, valaxy.cms.ts, a generated manifest, or package exports?
3. How can remote tools discover schemas without executing untrusted project/theme code?
4. How should core, themes, plugins, and individual sites merge or override schemas?
5. Which capabilities belong in v1: drafts, i18n, relations, media, preview, or only collections/frontmatter?
6. How should schema versions and migrations work across Valaxy and theme releases?
7. Can TypeScript-based site/theme configuration be edited safely, or should v1 treat it as read-only and focus on Markdown/YAML/JSON?
8. What is the smallest preview protocol that works for local tools and hosted services without coupling Valaxy to either?
9. Should the contract describe only content shape, or also workflow hints such as direct commit vs. branch/PR publishing?

Possible reference implementation

I am considering an independent project tentatively called Yunle CMS as one possible implementation of this contract, potentially with an optional hosted service in the future.

It would not be embedded in Valaxy, would not be the only supported consumer, and should not introduce Yunle- or CloudBase-specific dependencies into Valaxy. Other CMSs, editor extensions, and community tools should be equally able to implement the same contract.

Feedback is especially welcome from theme authors, plugin authors, users with custom frontmatter, and maintainers of tools that already read or modify Valaxy repositories.