From a070612018237c642351e9a82e371a02371210d1 Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Tue, 9 Jun 2026 17:42:28 +0100 Subject: [PATCH 1/6] docs(docusaurus): move version dropdown to left navbar; shorten label to 'main' Two navbar polish changes: - docsVersionDropdown moved from right (between Community and GitHub) to left (after API Reference), so it groups with content navigation rather than sitting between external links - current version label shortened from 'main (unreleased)' to 'main' for cleaner display in the dropdown Signed-off-by: Nigel Jones Assisted-by: Claude Code --- docs/docusaurus.config.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index c61d9dfa5..878180004 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -40,7 +40,7 @@ const config: Config = { lastVersion: 'current', versions: { current: { - label: 'main (unreleased)', + label: 'main', // path is added by the release pipeline (set-last-version.mjs) on // first final release, once a snapshot version exists as the default banner: 'none', @@ -170,6 +170,10 @@ const config: Config = { position: 'left', label: 'API Reference', }, + { + type: 'docsVersionDropdown', + position: 'left', + }, { href: 'https://mellea.ai/blogs/', label: 'Blog', @@ -180,10 +184,6 @@ const config: Config = { label: 'Community', position: 'right', }, - { - type: 'docsVersionDropdown', - position: 'right', - }, { href: 'https://github.com/generative-computing/mellea', label: 'GitHub', From b80bdaaee166c35441aeb009c80b7fa07a24853a Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Tue, 9 Jun 2026 17:47:51 +0100 Subject: [PATCH 2/6] docs(publishing): update version label refs; add fork preview instructions - Update two 'main (unreleased)' references to 'main' to match the label change in docusaurus.config.ts - Expand the fork PR note into a full 'Previewing from your own fork' section covering the GitHub Pages bootstrap pattern (docs/staging workaround) and the fork baseUrl difference Signed-off-by: Nigel Jones Assisted-by: Claude Code --- docs/PUBLISHING.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 4d08580f1..599054dcd 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -96,8 +96,8 @@ The `docs-publish.yml` workflow (`Docs` in GitHub Actions) runs these steps: Docusaurus versioning is integrated into the release pipeline: -- **Pre-release / dev builds:** the site shows `main (unreleased)` as the - only version — there are no snapshots yet. +- **Pre-release / dev builds:** the site shows `main` as the only version + — there are no snapshots yet. - **On each final release** (`publish-release.yml` with `bump_type: final` or `patch-final`): the `snapshot-docs` job runs `docusaurus docs:version X.Y.Z`, commits `versioned_docs/version-X.Y.Z/` @@ -105,12 +105,12 @@ Docusaurus versioning is integrated into the release pipeline: `workflow_dispatch`. (A `GITHUB_TOKEN` push cannot trigger a new workflow run, so the dispatch is explicit rather than relying on a path filter.) - **Version dropdown** in the navbar lets users switch between released - versions and `main (unreleased)`. + versions and `main`. No manual bootstrap is needed — the first final release run triggers `snapshot-docs` automatically, which creates the initial snapshot and updates `lastVersion`. Until the first final release, the site shows only -`main (unreleased)` in the version dropdown, which is correct. +`main` in the version dropdown, which is correct. ## Local development @@ -166,6 +166,18 @@ To preview the deployed site from a non-main branch: > with a permission error. Push the branch to the upstream repo and use > manual dispatch instead. +### Previewing from your own fork + +To get a live preview site from your fork (useful for reviewing visual changes before submitting a PR): + +1. **Enable GitHub Pages** on your fork: Settings → Pages → Source: `gh-pages` branch, root `/`. + - GitHub requires a branch to exist before Pages can be enabled. If `gh-pages` doesn't exist yet, push any content to a temporary `docs/staging` branch, enable Pages pointing at it, then switch to `gh-pages` once the first deployment creates it. +2. **Push your branch** to your fork (`git push origin my-branch`). +3. The `docs-publish.yml` workflow runs automatically — it builds the site with `baseUrl: /mellea/` (fork-aware) and deploys to `gh-pages` on your fork. +4. Your preview is live at `https://.github.io/mellea/`. + +> The fork `baseUrl` (`/mellea/`) differs from upstream (`/`). Internal links and assets will resolve correctly on the fork preview, but absolute URLs pointing to `docs.mellea.ai` will still go to the production site. + ## File reference | Path | Description | From 3594e2c53b7dbf5d00785e73caa50b77fcf03bad Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Tue, 9 Jun 2026 17:55:35 +0100 Subject: [PATCH 3/6] docs(publishing): simplify fork preview instructions Remove the docs/staging bootstrap step (peaceiris creates gh-pages automatically on first push) and the baseUrl explanation (handled transparently by the workflow). Signed-off-by: Nigel Jones Assisted-by: Claude Code --- docs/PUBLISHING.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 599054dcd..f477bee52 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -170,13 +170,9 @@ To preview the deployed site from a non-main branch: To get a live preview site from your fork (useful for reviewing visual changes before submitting a PR): -1. **Enable GitHub Pages** on your fork: Settings → Pages → Source: `gh-pages` branch, root `/`. - - GitHub requires a branch to exist before Pages can be enabled. If `gh-pages` doesn't exist yet, push any content to a temporary `docs/staging` branch, enable Pages pointing at it, then switch to `gh-pages` once the first deployment creates it. -2. **Push your branch** to your fork (`git push origin my-branch`). -3. The `docs-publish.yml` workflow runs automatically — it builds the site with `baseUrl: /mellea/` (fork-aware) and deploys to `gh-pages` on your fork. -4. Your preview is live at `https://.github.io/mellea/`. - -> The fork `baseUrl` (`/mellea/`) differs from upstream (`/`). Internal links and assets will resolve correctly on the fork preview, but absolute URLs pointing to `docs.mellea.ai` will still go to the production site. +1. **Push your branch** to your fork. The `docs-publish.yml` workflow runs automatically and deploys to the `gh-pages` branch on your fork, creating it if it doesn't exist. +2. **Enable GitHub Pages** on your fork: Settings → Pages → Source: `gh-pages` branch, root `/`. +3. Your preview is live at `https://.github.io/mellea/`. ## File reference From 85cbdaf24c6744dfa651e37392665759efff790b Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Mon, 15 Jun 2026 15:11:34 +0100 Subject: [PATCH 4/6] docs(docusaurus): use default version label; remove CLI reference page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the explicit 'main' label on the current (unreleased) version so Docusaurus uses its default 'Next'. This also removes the need for set-last-version.mjs to inject a path on first release — Docusaurus routes the current version to /next/ automatically. Remove the CLI reference page entry from the sidebar and its redirect rules from the config; update in-page 'CLI Reference' cross-links to point to the API Reference instead. Assisted-by: Claude Code Signed-off-by: Nigel Jones --- .github/scripts/set-last-version.mjs | 11 --------- docs/docs/advanced/lora-and-alora-adapters.md | 2 +- docs/docs/community/building-extensions.md | 2 +- .../how-to/evaluate-with-llm-as-a-judge.md | 2 +- docs/docs/how-to/m-decompose.md | 2 +- docs/docs/how-to/refactor-prompts-with-cli.md | 2 +- docs/docs/integrations/m-serve.md | 2 +- docs/docusaurus.config.ts | 23 ++----------------- docs/sidebars.ts | 1 - 9 files changed, 8 insertions(+), 39 deletions(-) diff --git a/.github/scripts/set-last-version.mjs b/.github/scripts/set-last-version.mjs index 14acadef8..473fca43f 100644 --- a/.github/scripts/set-last-version.mjs +++ b/.github/scripts/set-last-version.mjs @@ -20,16 +20,5 @@ if (updated === src) { } src = updated; -// Add path: 'main' to the current version block if not already present. -// This is a one-time insertion needed once a snapshot version exists as the -// default — before the first snapshot, current IS the default and needs no path. -if (!src.includes("path: 'main'")) { - src = src.replace( - /label: 'main \(unreleased\)',/, - "label: 'main (unreleased)',\n path: 'main',", - ); - console.log("Added path: 'main' to versions.current"); -} - writeFileSync(configPath, src); console.log(`Set lastVersion to '${version}' in ${configPath}`); diff --git a/docs/docs/advanced/lora-and-alora-adapters.md b/docs/docs/advanced/lora-and-alora-adapters.md index fa0aad481..8992a1a67 100644 --- a/docs/docs/advanced/lora-and-alora-adapters.md +++ b/docs/docs/advanced/lora-and-alora-adapters.md @@ -163,4 +163,4 @@ affect other sessions. **See also:** [Intrinsics](./intrinsics) | [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers) | -[CLI Reference](../reference/cli) +[API Reference](../api) diff --git a/docs/docs/community/building-extensions.md b/docs/docs/community/building-extensions.md index ea7af1357..561f443a0 100644 --- a/docs/docs/community/building-extensions.md +++ b/docs/docs/community/building-extensions.md @@ -295,7 +295,7 @@ class EchoBackend(Backend): ``` The full `Backend` abstract interface is documented in the -[API reference](/api/mellea/core/backend). +[API reference](../api). > **Note:** Production backends handle async streaming, tokenization, and error > recovery. Study an existing backend in `mellea/backends/` before implementing diff --git a/docs/docs/how-to/evaluate-with-llm-as-a-judge.md b/docs/docs/how-to/evaluate-with-llm-as-a-judge.md index f7bb56123..d653c359f 100644 --- a/docs/docs/how-to/evaluate-with-llm-as-a-judge.md +++ b/docs/docs/how-to/evaluate-with-llm-as-a-judge.md @@ -207,4 +207,4 @@ requirements. `sample_generations` lists every attempt made. **See also:** [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers) | [Handling Exceptions and Failures](../how-to/handling-exceptions) | -[CLI Reference](../reference/cli) +[API Reference](../api) diff --git a/docs/docs/how-to/m-decompose.md b/docs/docs/how-to/m-decompose.md index 3074145ae..bc67438c0 100644 --- a/docs/docs/how-to/m-decompose.md +++ b/docs/docs/how-to/m-decompose.md @@ -123,4 +123,4 @@ For tasks that fit comfortably in a single prompt, use `m.instruct()` directly. --- -**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [CLI Reference](../reference/cli) +**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [API Reference](../api) diff --git a/docs/docs/how-to/refactor-prompts-with-cli.md b/docs/docs/how-to/refactor-prompts-with-cli.md index fbd029082..827ffc60f 100644 --- a/docs/docs/how-to/refactor-prompts-with-cli.md +++ b/docs/docs/how-to/refactor-prompts-with-cli.md @@ -339,5 +339,5 @@ and `"llm"` for quality checks that require LLM-as-a-judge evaluation. typed returns, and context steering to the generated pipeline - [Enforce Structured Output](../how-to/enforce-structured-output) — constrain subtask outputs to Pydantic models or `Literal` values -- [CLI Reference](../reference/cli) — complete flag and option reference for +- [API Reference](../api) — complete flag and option reference for all `m` subcommands diff --git a/docs/docs/integrations/m-serve.md b/docs/docs/integrations/m-serve.md index 989c0ce91..607d0f8cf 100644 --- a/docs/docs/integrations/m-serve.md +++ b/docs/docs/integrations/m-serve.md @@ -113,4 +113,4 @@ print(response.choices[0].message.content) **See also:** [Context and Sessions](../concepts/context-and-sessions) | [Backends and Configuration](../how-to/backends-and-configuration) | -[CLI Reference](../reference/cli) +[API Reference](../api) diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 878180004..8a4874397 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -36,13 +36,10 @@ const config: Config = { showLastUpdateTime: true, editUrl: 'https://github.com/generative-computing/mellea/edit/main/', includeCurrentVersion: true, - // set-last-version.mjs matches these lines with exact regexes — do not reformat + // set-last-version.mjs matches this line with an exact regex — do not reformat lastVersion: 'current', versions: { current: { - label: 'main', - // path is added by the release pipeline (set-last-version.mjs) on - // first final release, once a snapshot version exists as the default banner: 'none', }, }, @@ -93,23 +90,7 @@ const config: Config = { {from: '/dev/requirement-alora-rerouting', to: '/advanced/lora-and-alora-adapters'}, {from: '/dev/spans', to: '/observability/tracing'}, {from: '/dev/tool-calling', to: '/how-to/tools-and-agents'}, - {from: '/api/cli/m', to: '/reference/cli'}, - {from: '/api/cli/alora/commands', to: '/reference/cli'}, - {from: '/api/cli/alora/intrinsic_uploader', to: '/reference/cli'}, - {from: '/api/cli/alora/readme_generator', to: '/reference/cli'}, - {from: '/api/cli/alora/train', to: '/reference/cli'}, - {from: '/api/cli/alora/upload', to: '/reference/cli'}, - {from: '/api/cli/decompose/decompose', to: '/reference/cli'}, - {from: '/api/cli/decompose/pipeline', to: '/reference/cli'}, - {from: '/api/cli/decompose/utils', to: '/reference/cli'}, - {from: '/api/cli/eval/commands', to: '/reference/cli'}, - {from: '/api/cli/eval/eval', to: '/reference/cli'}, - {from: '/api/cli/eval/runner', to: '/reference/cli'}, - {from: '/api/cli/serve/app', to: '/reference/cli'}, - {from: '/api/cli/serve/models', to: '/reference/cli'}, - {from: '/api/cli/fix/commands', to: '/reference/cli'}, - {from: '/api/cli/fix/async_fixer', to: '/reference/cli'}, - {from: '/api/cli/fix/genstub_fixer', to: '/reference/cli'}, + {from: '/guide/generative-functions', to: '/how-to/generative-functions'}, {from: '/guide/tools-and-agents', to: '/how-to/tools-and-agents'}, {from: '/guide/working-with-data', to: '/how-to/working-with-data'}, diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 2cd785530..1f3e73ed3 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -124,7 +124,6 @@ const sidebars: SidebarsConfig = { label: 'Reference', items: [ 'reference/glossary', - 'reference/cli', ], }, { From 4f5b7618b451928af744cebd8d233e5fb64beeb5 Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Mon, 15 Jun 2026 16:08:05 +0100 Subject: [PATCH 5/6] docs(docusaurus): revert CLI reference removal to separate PR CLI reference removal has loose ends (generator, ast link, CONTRIBUTING_DOCS) that warrant a dedicated PR. Restore the sidebar entry, redirects, and in-page links to keep this PR focused on navbar and version label changes. Assisted-by: Claude Code Signed-off-by: Nigel Jones --- docs/docs/advanced/lora-and-alora-adapters.md | 2 +- docs/docs/community/building-extensions.md | 2 +- .../how-to/evaluate-with-llm-as-a-judge.md | 2 +- docs/docs/how-to/m-decompose.md | 2 +- docs/docs/how-to/refactor-prompts-with-cli.md | 2 +- docs/docs/integrations/m-serve.md | 2 +- docs/docusaurus.config.ts | 18 +++++++++++++++++- docs/sidebars.ts | 1 + 8 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/docs/advanced/lora-and-alora-adapters.md b/docs/docs/advanced/lora-and-alora-adapters.md index 8992a1a67..fa0aad481 100644 --- a/docs/docs/advanced/lora-and-alora-adapters.md +++ b/docs/docs/advanced/lora-and-alora-adapters.md @@ -163,4 +163,4 @@ affect other sessions. **See also:** [Intrinsics](./intrinsics) | [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers) | -[API Reference](../api) +[CLI Reference](../reference/cli) diff --git a/docs/docs/community/building-extensions.md b/docs/docs/community/building-extensions.md index 561f443a0..ea7af1357 100644 --- a/docs/docs/community/building-extensions.md +++ b/docs/docs/community/building-extensions.md @@ -295,7 +295,7 @@ class EchoBackend(Backend): ``` The full `Backend` abstract interface is documented in the -[API reference](../api). +[API reference](/api/mellea/core/backend). > **Note:** Production backends handle async streaming, tokenization, and error > recovery. Study an existing backend in `mellea/backends/` before implementing diff --git a/docs/docs/how-to/evaluate-with-llm-as-a-judge.md b/docs/docs/how-to/evaluate-with-llm-as-a-judge.md index d653c359f..f7bb56123 100644 --- a/docs/docs/how-to/evaluate-with-llm-as-a-judge.md +++ b/docs/docs/how-to/evaluate-with-llm-as-a-judge.md @@ -207,4 +207,4 @@ requirements. `sample_generations` lists every attempt made. **See also:** [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers) | [Handling Exceptions and Failures](../how-to/handling-exceptions) | -[API Reference](../api) +[CLI Reference](../reference/cli) diff --git a/docs/docs/how-to/m-decompose.md b/docs/docs/how-to/m-decompose.md index bc67438c0..3074145ae 100644 --- a/docs/docs/how-to/m-decompose.md +++ b/docs/docs/how-to/m-decompose.md @@ -123,4 +123,4 @@ For tasks that fit comfortably in a single prompt, use `m.instruct()` directly. --- -**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [API Reference](../api) +**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [CLI Reference](../reference/cli) diff --git a/docs/docs/how-to/refactor-prompts-with-cli.md b/docs/docs/how-to/refactor-prompts-with-cli.md index 827ffc60f..fbd029082 100644 --- a/docs/docs/how-to/refactor-prompts-with-cli.md +++ b/docs/docs/how-to/refactor-prompts-with-cli.md @@ -339,5 +339,5 @@ and `"llm"` for quality checks that require LLM-as-a-judge evaluation. typed returns, and context steering to the generated pipeline - [Enforce Structured Output](../how-to/enforce-structured-output) — constrain subtask outputs to Pydantic models or `Literal` values -- [API Reference](../api) — complete flag and option reference for +- [CLI Reference](../reference/cli) — complete flag and option reference for all `m` subcommands diff --git a/docs/docs/integrations/m-serve.md b/docs/docs/integrations/m-serve.md index 607d0f8cf..989c0ce91 100644 --- a/docs/docs/integrations/m-serve.md +++ b/docs/docs/integrations/m-serve.md @@ -113,4 +113,4 @@ print(response.choices[0].message.content) **See also:** [Context and Sessions](../concepts/context-and-sessions) | [Backends and Configuration](../how-to/backends-and-configuration) | -[API Reference](../api) +[CLI Reference](../reference/cli) diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 8a4874397..205e9ac9d 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -90,7 +90,23 @@ const config: Config = { {from: '/dev/requirement-alora-rerouting', to: '/advanced/lora-and-alora-adapters'}, {from: '/dev/spans', to: '/observability/tracing'}, {from: '/dev/tool-calling', to: '/how-to/tools-and-agents'}, - + {from: '/api/cli/m', to: '/reference/cli'}, + {from: '/api/cli/alora/commands', to: '/reference/cli'}, + {from: '/api/cli/alora/intrinsic_uploader', to: '/reference/cli'}, + {from: '/api/cli/alora/readme_generator', to: '/reference/cli'}, + {from: '/api/cli/alora/train', to: '/reference/cli'}, + {from: '/api/cli/alora/upload', to: '/reference/cli'}, + {from: '/api/cli/decompose/decompose', to: '/reference/cli'}, + {from: '/api/cli/decompose/pipeline', to: '/reference/cli'}, + {from: '/api/cli/decompose/utils', to: '/reference/cli'}, + {from: '/api/cli/eval/commands', to: '/reference/cli'}, + {from: '/api/cli/eval/eval', to: '/reference/cli'}, + {from: '/api/cli/eval/runner', to: '/reference/cli'}, + {from: '/api/cli/serve/app', to: '/reference/cli'}, + {from: '/api/cli/serve/models', to: '/reference/cli'}, + {from: '/api/cli/fix/commands', to: '/reference/cli'}, + {from: '/api/cli/fix/async_fixer', to: '/reference/cli'}, + {from: '/api/cli/fix/genstub_fixer', to: '/reference/cli'}, {from: '/guide/generative-functions', to: '/how-to/generative-functions'}, {from: '/guide/tools-and-agents', to: '/how-to/tools-and-agents'}, {from: '/guide/working-with-data', to: '/how-to/working-with-data'}, diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 1f3e73ed3..2cd785530 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -124,6 +124,7 @@ const sidebars: SidebarsConfig = { label: 'Reference', items: [ 'reference/glossary', + 'reference/cli', ], }, { From 1519e011551427720801987ad119b2ef44ce93bf Mon Sep 17 00:00:00 2001 From: Nigel Jones Date: Mon, 15 Jun 2026 16:12:09 +0100 Subject: [PATCH 6/6] docs(publishing): update version label refs from 'main' to 'Next' Docusaurus default label for the unreleased version is 'Next', not 'main'. Update prose in PUBLISHING.md to match what actually renders. Assisted-by: Claude Code Signed-off-by: Nigel Jones --- docs/PUBLISHING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index f477bee52..abf9e126e 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -96,7 +96,7 @@ The `docs-publish.yml` workflow (`Docs` in GitHub Actions) runs these steps: Docusaurus versioning is integrated into the release pipeline: -- **Pre-release / dev builds:** the site shows `main` as the only version +- **Pre-release / dev builds:** the site shows `Next` as the only version — there are no snapshots yet. - **On each final release** (`publish-release.yml` with `bump_type: final` or `patch-final`): the `snapshot-docs` job runs @@ -105,12 +105,12 @@ Docusaurus versioning is integrated into the release pipeline: `workflow_dispatch`. (A `GITHUB_TOKEN` push cannot trigger a new workflow run, so the dispatch is explicit rather than relying on a path filter.) - **Version dropdown** in the navbar lets users switch between released - versions and `main`. + versions and `Next`. No manual bootstrap is needed — the first final release run triggers `snapshot-docs` automatically, which creates the initial snapshot and updates `lastVersion`. Until the first final release, the site shows only -`main` in the version dropdown, which is correct. +`Next` in the version dropdown, which is correct. ## Local development