Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ jobs:
run: echo "version=" >> $GITHUB_OUTPUT

- run: npm ci
- run: npm test
- run: npm run build
env:
DOCS_VERSION: ${{ steps.set-version.outputs.version }}
Expand Down
52 changes: 52 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ concurrency:
jobs:
build:
runs-on: ubuntu-latest
environment: github-pages
permissions:
contents: read # Only reads for checkout; pushes to gh-pages use the platform-mesh-publisher app token
steps:
Expand Down Expand Up @@ -84,3 +85,54 @@ jobs:
include: |
index.html
llms.txt

versions:
name: Update shared version list
needs: build
if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release-') }}
runs-on: ubuntu-latest
environment: github-pages
# Every release writes the same root-level file. Read gh-pages only after
# acquiring this lock, so a later job never publishes an older snapshot.
concurrency:
group: pages-shared-versions
cancel-in-progress: false
permissions:
contents: read
steps:
# Keep the generator centralized on main, even for release deployments.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
ref: main
persist-credentials: false

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
ref: gh-pages
path: deployed-docs
persist-credentials: false

- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: 26
package-manager-cache: false

- name: Generate versions.js from deployed documentation
run: node hack/generate-versions.mjs deployed-docs shared-versions/versions.js

- id: app-token
name: Generate platform-mesh-publisher app token
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
app-id: "1415820" # platform-mesh-publisher
private-key: ${{ secrets.PM_PUBLISHER_PRIVATE_KEY }}
permission-contents: write

- uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4
with:
token: ${{ steps.app-token.outputs.token }}
folder: shared-versions
branch: gh-pages
target-folder: .
clean: false
force: false
5 changes: 4 additions & 1 deletion .vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,10 @@ const base = 'DOCS_VERSION' in process.env && process.env.DOCS_VERSION != ''
export default withMermaid({
title: "Platform Mesh",
head: [
['link', { rel: 'icon', href: `${base}favicon.ico` }]
['link', { rel: 'icon', href: `${base}favicon.ico` }],
// Deliberately synchronous: the shared version list must be available before
// Vue mounts. Use the site root, not this build's release/preview base path.
['script', { src: '/versions.js' }]
],

base,
Expand Down
56 changes: 34 additions & 22 deletions .vitepress/theme/components/VersionSelector.vue
Original file line number Diff line number Diff line change
Expand Up @@ -22,25 +22,26 @@
import { ref, onMounted } from 'vue'

interface Version {
// name is the name of the directory where this version has its docs,
// usually identical to the branch name
name: string
// label is how the version is shown in the dropdown
label: string
// rootOnly should be set to true only for pre-0.3 versions for which the
// directory structure differs greatly from more recent versions. This
// prevents sending users to non-existent pages when they switch versions.
rootOnly?: boolean
}

// Define available versions - update this list when adding new versions.
// Set rootOnly: true for versions whose URL structure differs from the current
// docs layout (pre-v0.3 used a different directory structure), so switching
// to them always lands on the version root instead of trying to map the
// current path.
const versions: Version[] = [
{ name: 'main', label: 'main (latest)' },
{ name: 'release-26.10', label: 'v26.10' },
{ name: 'release-0.5', label: 'v0.5' },
{ name: 'release-0.4', label: 'v0.4' },
{ name: 'release-0.3', label: 'v0.3' },
{ name: 'release-0.2', label: 'v0.2', rootOnly: true },
{ name: 'release-0.1', label: 'v0.1', rootOnly: true },
]
declare global {
interface Window {
PLATFORM_MESH_VERSIONS?: Version[]
}
}

// The root-level /versions.js is shared by all documentation releases.
// Keep server rendering independent of window; load the list on mount.
const versions = ref<Version[]>([{ name: 'main', label: 'main (latest)' }])

const currentVersion = ref<string>('')
const isPreview = ref<boolean>(false)
Expand All @@ -61,12 +62,10 @@ function getCurrentVersion(): string {
const path = window.location.pathname
const segments = path.split('/').filter(Boolean)

// Check if first segment matches a known version
if (segments.length > 0) {
const firstSegment = segments[0]
if (versions.some(v => v.name === firstSegment)) {
return firstSegment
}
// Detect the current release even when the shared script is unavailable.
const firstSegment = segments[0]
if (firstSegment === 'main' || /^release-\d+\.\d+$/.test(firstSegment || '')) {
return firstSegment
}

// Default to main if no version detected
Expand All @@ -76,7 +75,7 @@ function getCurrentVersion(): string {
function switchVersion(): void {
if (typeof window === 'undefined') return

const selected = versions.find(v => v.name === currentVersion.value)
const selected = versions.value.find(v => v.name === currentVersion.value)

if (selected?.rootOnly) {
window.location.href = `/${currentVersion.value}/`
Expand All @@ -88,7 +87,7 @@ function switchVersion(): void {

// Remove the version from the path if it exists
let pathWithoutVersion = ''
if (segments.length > 0 && versions.some(v => v.name === segments[0])) {
if (segments.length > 0 && versions.value.some(v => v.name === segments[0])) {
pathWithoutVersion = '/' + segments.slice(1).join('/')
} else {
pathWithoutVersion = currentPath
Expand All @@ -111,6 +110,19 @@ function switchVersion(): void {
onMounted(() => {
isPreview.value = isPreviewContext()
currentVersion.value = getCurrentVersion()
if (window.PLATFORM_MESH_VERSIONS?.length) {
versions.value = [...window.PLATFORM_MESH_VERSIONS]
}

// Local builds, a failed script request, or a stale cached list should still
// show the current version and allow navigation back to main.
if (!versions.value.some(v => v.name === currentVersion.value)) {
versions.value.push({
name: currentVersion.value,
label: `v${currentVersion.value.replace(/^release-/, '')}`,
rootOnly: ['release-0.1', 'release-0.2'].includes(currentVersion.value),
})
}
})
</script>

Expand Down
48 changes: 48 additions & 0 deletions hack/generate-versions.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
#!/usr/bin/env node
// Generate the shared script from successfully deployed documentation, not
// branches that might not have a working deployment yet. No npm dependencies.
import { access, mkdir, readdir, writeFile } from 'node:fs/promises'
import { dirname, join, resolve } from 'node:path'
import { pathToFileURL } from 'node:url'

export async function generateVersions(deploymentDirectory) {
const versions = []
for (const entry of await readdir(deploymentDirectory, { withFileTypes: true })) {
if (!entry.isDirectory()) continue
if (entry.name !== 'main' && !/^release-\d+\.\d+$/.test(entry.name)) continue
try {
await access(join(deploymentDirectory, entry.name, 'index.html'))
} catch (error) {
if (error.code === 'ENOENT') continue
throw error
}
versions.push({
name: entry.name,
label: entry.name === 'main' ? 'main (latest)' : `v${entry.name.slice('release-'.length)}`,
...(['release-0.1', 'release-0.2'].includes(entry.name) ? { rootOnly: true } : {}),
})
}
return versions.sort((a, b) => {
if (a.name === 'main') return -1
if (b.name === 'main') return 1
return b.name.localeCompare(a.name, 'en', { numeric: true })
})
}

export function renderVersions(versions) {
return '// Generated from deployed documentation. Do not edit.\n'
+ `window.PLATFORM_MESH_VERSIONS = ${JSON.stringify(versions, null, 2)};\n`
}

if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
const [, , deploymentDirectory, outputFile] = process.argv
if (!deploymentDirectory || !outputFile) {
console.error('Usage: node hack/generate-versions.mjs <gh-pages-directory> <output-file>')
process.exitCode = 1
} else {
const versions = await generateVersions(deploymentDirectory)
if (!versions.length) throw new Error('No deployed documentation versions found')
await mkdir(dirname(outputFile), { recursive: true })
await writeFile(outputFile, renderVersions(versions))
}
}
42 changes: 42 additions & 0 deletions hack/generate-versions.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import assert from 'node:assert/strict'
import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { test } from 'node:test'
import { runInNewContext } from 'node:vm'
import { generateVersions, renderVersions } from './generate-versions.mjs'

test('discovers deployed releases, sorts numerically, and preserves legacy navigation', async t => {
const root = await mkdtemp(join(tmpdir(), 'pm-versions-'))
t.after(() => rm(root, { recursive: true, force: true }))
for (const name of [
'main', 'release-0.1', 'release-0.2', 'release-0.3', 'release-0.5',
'release-26.9', 'release-26.10', 'release-27.1', 'pr-preview',
'release-unpublished', 'release-26.11',
]) {
await mkdir(join(root, name))
if (name !== 'release-26.11') await writeFile(join(root, name, 'index.html'), '')
}
await writeFile(join(root, 'release-28.1'), 'not a directory')

const versions = await generateVersions(root)
assert.deepEqual(versions.map(v => v.name), [
'main', 'release-27.1', 'release-26.10', 'release-26.9',
'release-0.5', 'release-0.3', 'release-0.2', 'release-0.1',
])
assert.equal(versions[0].label, 'main (latest)')
assert.equal(versions[2].label, 'v26.10')
assert.deepEqual(versions.filter(v => v.rootOnly).map(v => v.name), [
'release-0.2', 'release-0.1',
])

const window = {}
runInNewContext(renderVersions(versions), { window })
assert.equal(JSON.stringify(window.PLATFORM_MESH_VERSIONS), JSON.stringify(versions))
})

test('an empty deployment contains no versions', async t => {
const root = await mkdtemp(join(tmpdir(), 'pm-versions-'))
t.after(() => rm(root, { recursive: true, force: true }))
assert.deepEqual(await generateVersions(root), [])
})
73 changes: 38 additions & 35 deletions hack/how-to.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,38 +163,40 @@ git push -u origin release-0.2

### Updating the Version Selector

After creating a new release branch, add it to the dropdown:
No manual version-list updates are needed. Every successful documentation deployment
runs a serialized `versions` job in `.github/workflows/release.yml`. It checks out
`gh-pages`, discovers deployed `main/` and `release-X.Y/` directories containing an
`index.html`, and publishes a single `/versions.js` at the site root. Releases are
sorted numerically, newest first, with main at the top. A branch without a deployed
site is not advertised.

Every documentation build includes this shared script synchronously in `<head>`,
before Vue initializes the dropdown. It is intentionally loaded from `/versions.js`,
not from the release's base path. Old releases therefore see newly deployed versions
without being rebuilt. Browser/GitHub Pages caching may briefly delay updates.
If the script is unavailable, the dropdown falls back to main and the current release.
PR previews continue to hide the selector.

The generator lives in `hack/generate-versions.mjs` and is always loaded from main
by the deployment job. It retains `rootOnly` navigation for releases 0.1 and 0.2.
Run its tests with `npm test`.

Both publishing jobs use the `github-pages` GitHub environment. In repository
**Settings → Environments → github-pages**, ensure the deployment branch policy
allows `main` and `release-*` before deploying these workflow changes to release
branches. Environment policies apply to the workflow's source branch, even though
it publishes files to `gh-pages`.

**Local testing:** a single-version VitePress server does not have the root-level
shared script; a 404 for `/versions.js` is expected and exercises the fallback.
To test the full dropdown with the multi-version `test-deploy/` setup above, generate
the shared script before serving that directory:

```bash
# 1. Edit the version selector component
git checkout main
```

Edit `.vitepress/theme/components/VersionSelector.vue`:

```typescript
const versions: Version[] = [
{ name: 'main', label: 'main (latest)' },
{ name: 'release-0.3', label: 'v0.3' }, // Add new versions here
{ name: 'release-0.2', label: 'v0.2' },
{ name: 'release-0.1', label: 'v0.1' },
]
node hack/generate-versions.mjs test-deploy test-deploy/versions.js
```

```bash
# 2. Commit and push
git add .vitepress/theme/components/VersionSelector.vue
git commit -m "Add release-0.3 to version selector"
git push origin main
```

**Apply to other branches (optional):**
```bash
# Update the dropdown on release branches too
git checkout release-0.2
git cherry-pick <commit-hash-from-main>
git push origin release-0.2
```
You can use the same command with a local checkout of `gh-pages` as the first argument.

### Updating Release Documentation

Expand Down Expand Up @@ -515,15 +517,16 @@ git push origin release-0.3

### Version Selector Management

**Keep it updated:**
- Add new versions to dropdown when created
- List versions in reverse chronological order (newest first, except main)
- Use clear labels (`main (latest)`, `v0.3`, `v0.2`)
The shared `/versions.js` is regenerated automatically after each documentation
deployment. Do not edit the generated file or maintain per-branch version lists.

**Remove old versions:**
1. Delete the branch: `git push origin --delete release-0.1`
2. Remove from dropdown in `VersionSelector.vue`
3. Optionally: manually delete from `gh-pages` branch
1. Delete the source branch if it is no longer needed.
2. Delete its deployed directory (for example `release-0.1/`) from `gh-pages`.
3. Run the release workflow on main to regenerate `/versions.js`.

Deleting only a source branch does not unpublish its documentation or remove it
from the dropdown. The deployed directories are the source of truth.

### Testing Before Merging

Expand Down
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
"scripts": {
"dev": "vitepress dev",
"build": "vitepress build",
"preview": "vitepress preview"
"preview": "vitepress preview",
"test": "node --test hack/*.test.mjs"
},
"dependencies": {
"markdown-it-footnote": "^4.0.0",
Expand Down
Loading