Skip to content

Commit 963052c

Browse files
tmlmttmlmt
authored
docs: generate and deploy for both v2 and v3 (#85)
# Description Implemented versioned documentation support to maintain both v2 and v3 documentation simultaneously. This change allows users to access different versions of the documentation based on the release tag. Key changes: - Modified CI workflow to build and deploy both v2 (from main branch) and v3 (from release tag) documentation - Added version detection logic to display appropriate version information - Created a custom VitePress layout with a warning banner for pre-release versions - Configured documentation base paths to support version-specific URLs - Added version switcher in the navigation menu ## Type of change - [x] New feature (non-breaking change which adds functionality) - [x] This change requires a documentation update # How Has This Been Tested? - [x] Verified documentation builds correctly for both v2 and v3 versions - [x] Tested version switcher navigation between documentation versions - [x] Confirmed pre-release banner displays correctly on alpha/beta versions # Checklist: - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] I have run `pnpm lint` and my changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] Any dependent changes have been merged and published in downstream modules
1 parent 0ef9943 commit 963052c

File tree

6 files changed

+119
-9
lines changed

6 files changed

+119
-9
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -58,20 +58,44 @@ jobs:
5858
if: github.event_name == 'release'
5959
steps:
6060
- uses: actions/checkout@v4
61+
with:
62+
ref: main
63+
- uses: pnpm/action-setup@v4
6164
- uses: actions/setup-node@v4
6265
with:
6366
node-version: 22
64-
registry-url: "https://registry.npmjs.org/"
65-
- uses: pnpm/action-setup@v4
66-
- run: pnpm install
67-
- name: Build docs
67+
cache: "pnpm"
68+
- name: Install dependencies (main branch)
69+
run: pnpm install
70+
- name: Build v2 docs from main branch
6871
run: pnpm docs:build
72+
- name: Move v2 docs to combined folder
73+
run: |
74+
mkdir -p combined/v2
75+
mv docs/.vitepress/dist/* combined/v2/
76+
- name: Checkout release tag
77+
uses: actions/checkout@v4
78+
with:
79+
ref: ${{ github.ref }}
80+
clean: false
81+
- name: Install dependencies (release tag)
82+
run: pnpm install
83+
- name: Build and move v3 docs if v3 release
84+
run: |
85+
TAG_NAME="${{ github.ref_name }}"
86+
if [[ "$TAG_NAME" == v3* ]]; then
87+
pnpm docs:build
88+
mkdir -p combined/v3
89+
mv docs/.vitepress/dist/* combined/v3/
90+
fi
91+
- name: Copy v2 docs to root for default access
92+
run: cp -r combined/v2/* combined/
6993
- name: Deploy docs to production server
7094
uses: easingthemes/ssh-deploy@main
7195
env:
7296
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
7397
REMOTE_HOST: ${{ secrets.SSH_HOST }}
7498
REMOTE_USER: ${{ secrets.SSH_USER }}
7599
REMOTE_PORT: ${{ secrets.SSH_PORT }}
76-
SOURCE: "docs/.vitepress/dist/."
100+
SOURCE: "combined/."
77101
TARGET: ${{ secrets.TARGET_DIR_DOCS }}

‎docs/.vitepress/config.mts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,31 @@
11
import { defineConfig } from "vitepress";
2-
// eslint-disable-next-line @typescript-eslint/ban-ts-comment -- avoiding error when developing the docs locally
3-
// @ts-ignore: linting before typedoc is generated will throw an error here
2+
// eslint-disable-next-line @typescript-eslint/ban-ts-comment -- avoiding error when developing the docs locally
3+
// @ts-ignore: linting before typedoc is generated will throw an error here
44
import typedocSidebar from "../api/typedoc-sidebar.json";
5+
import { fullVersion, majorVersion, majorNumber } from "./version";
56

67
// https://vitepress.dev/reference/site-config
78
export default defineConfig({
89
title: "@tmlmt/cooklang-parser",
910
description: "Documentation for the npm package @tmlmt/cooklang-parser",
11+
base: `/${majorVersion}/`,
1012
themeConfig: {
1113
// https://vitepress.dev/reference/default-theme-config
1214
nav: [
1315
{ text: "Home", link: "/" },
14-
{ text: "Guide", link: "/guide-cooklang-specs"},
16+
{ text: "Guide", link: "/guide-cooklang-specs" },
1517
{ text: "API", link: "/api/classes/Recipe" },
1618
{ text: "Examples", link: "/examples-scaling-recipes" },
19+
{
20+
text: fullVersion,
21+
items: [
22+
{ text: fullVersion, link: "/" },
23+
{
24+
text: majorNumber === 2 ? "v3" : "v2",
25+
link: majorNumber === 2 ? "../v3/" : "../v2/",
26+
},
27+
],
28+
},
1729
],
1830

1931
sidebar: [

‎docs/.vitepress/theme/Layout.vue‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<script setup lang="ts">
2+
import DefaultTheme from "vitepress/theme";
3+
import { isPrerelease, majorVersion } from "../version";
4+
5+
const { Layout } = DefaultTheme;
6+
</script>
7+
8+
<template>
9+
<Layout>
10+
<template #layout-top>
11+
<div v-if="isPrerelease" class="prerelease-banner top-banner">
12+
⚠️ This is pre-release documentation for {{ majorVersion }}. For stable docs,
13+
visit <a href="../v2/">v2</a>.
14+
</div>
15+
<component v-if="isPrerelease" :is="'style'">
16+
:root { --vp-layout-top-height: 37px; }
17+
.VPHome { margin-bottom: 96px !important; }
18+
</component>
19+
</template>
20+
</Layout>
21+
</template>
22+
23+
<style scoped>
24+
.prerelease-banner.top-banner {
25+
background: #fff3cd;
26+
border-bottom: 1px solid #ffc107;
27+
color: #856404;
28+
padding: 0.5rem 1rem;
29+
text-align: center;
30+
position: fixed;
31+
top: 0;
32+
left: 0;
33+
right: 0;
34+
z-index: 50;
35+
}
36+
37+
.prerelease-banner a {
38+
color: #533f03;
39+
font-weight: 600;
40+
text-decoration: underline;
41+
}
42+
43+
.prerelease-banner a:hover {
44+
color: #1a1400;
45+
}
46+
</style>

‎docs/.vitepress/theme/index.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import DefaultTheme from "vitepress/theme";
2+
import type { DefineComponent } from "vue";
3+
import Layout from "./Layout.vue";
4+
import type { Theme } from "vitepress";
5+
6+
export default {
7+
extends: DefaultTheme,
8+
Layout: Layout as DefineComponent,
9+
} satisfies Theme;

‎docs/.vitepress/version.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import pkg from "../../package.json";
2+
3+
const version = pkg.version;
4+
5+
/** Full version string with 'v' prefix, e.g., "v2.1.7" or "v3.0.0-alpha.1" */
6+
export const fullVersion = `v${version}`;
7+
8+
/** Major version with 'v' prefix, e.g., "v2" or "v3" */
9+
export const majorVersion = `v${version.split(".")[0]}`;
10+
11+
/** Major version number, e.g., 2 or 3 */
12+
export const majorNumber = parseInt(version.split(".")[0], 10);
13+
14+
/** True if this is a prerelease version (contains a hyphen, e.g., "3.0.0-alpha.1") */
15+
export const isPrerelease = version.includes("-");

‎eslint.config.mjs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@ export default defineConfig(
2222
},
2323
parserOptions: {
2424
projectService: {
25-
allowDefaultProject: ["docs/.vitepress/config.mts"],
25+
allowDefaultProject: [
26+
"docs/.vitepress/config.mts",
27+
"docs/.vitepress/*/*.ts",
28+
"docs/.vitepress/*.ts",
29+
],
2630
},
2731
tsconfigRootDir: import.meta.dirname,
2832
},

0 commit comments

Comments
 (0)