Skip to content

Commit 8d0f30f

Browse files
MossakaMossaka
authored
Merge branch 'main' into copilot/add-installation-page-to-docs
Signed-off-by: Jiaxiao Zhou <[email protected]>
2 parents eb851cf + 9bd0654 commit 8d0f30f

File tree

12 files changed

+2566
-4
lines changed

12 files changed

+2566
-4
lines changed

‎.github/instructions/docs.instructions.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
applyTo: "docs/**/*.md"
3+
---
4+
5+
# Documentation Changes
6+
7+
When working on documentation changes that affect visual presentation or layout, **always use Playwright** to display and capture visual changes. This helps reviewers understand the impact of documentation modifications.
8+
9+
## Running the Documentation Locally
10+
11+
The project uses [mdbook](https://rust-lang.github.io/mdBook/) for documentation. Use the following commands:
12+
13+
- **Build the docs**: `just docs-build` - Builds the documentation to `docs/book/`
14+
- **Serve with auto-reload**: `just docs-watch` - Serves the docs at `http://localhost:3000` with live reload
15+
- **Serve and open browser**: `just docs-serve` - Serves the docs and automatically opens in your browser
16+
17+
Alternatively, you can use mdbook directly:
18+
```bash
19+
cd docs
20+
mdbook serve # Serve with live reload
21+
mdbook build # Build static HTML
22+
```
23+
24+
### Important: Local vs. Production URL Structure
25+
26+
The documentation uses a multi-version setup for production deployment on GitHub Pages, but `mdbook serve` doesn't support this structure locally.
27+
28+
**Local development** (with `mdbook serve`):
29+
- Navigate directly to `http://localhost:3000/overview.html` or any specific page
30+
- The version picker dropdown will not work locally (it's designed for the multi-version production site)
31+
- Root `http://localhost:3000/` may show a redirect page - this is expected
32+
33+
**Production** (GitHub Pages):
34+
- Full URL: `https://microsoft.github.io/wassette/latest/overview.html`
35+
- Root redirect: `https://microsoft.github.io/wassette/` → `https://microsoft.github.io/wassette/latest/`
36+
- Version picker works correctly across `/latest/`, `/v0.3.0/`, etc.
37+
38+
## Using Playwright for Documentation
39+
40+
- Use `playwright-browser_navigate` to load the documentation page
41+
- Use `playwright-browser_take_screenshot` to capture the visual state before and after changes
42+
- Compare screenshots to highlight differences in layout, formatting, or content presentation
43+
- Include screenshots in your progress reports to show visual impact
44+
45+
This ensures that documentation changes are properly validated and reviewers can see the actual visual impact of the modifications.

‎.github/workflows/docs.yml‎

Lines changed: 149 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ on:
66
paths:
77
- 'docs/**'
88
- '.github/workflows/docs.yml'
9+
tags:
10+
- 'v*'
911
pull_request:
1012
branches: [ "main" ]
1113
paths:
@@ -48,19 +50,164 @@ jobs:
4850
cargo install mdbook-tabs
4951
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
5052
53+
- name: Install mdbook-mermaid
54+
run: |
55+
curl -sSL https://github.com/badboy/mdbook-mermaid/releases/download/v0.14.0/mdbook-mermaid-v0.14.0-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
56+
echo "$GITHUB_WORKSPACE/bin" >> $GITHUB_PATH
57+
5158
- name: Setup Pages
5259
id: pages
5360
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
5461

62+
- name: Determine version
63+
id: version
64+
run: |
65+
if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
66+
VERSION="${{ github.ref_name }}"
67+
else
68+
VERSION="latest"
69+
fi
70+
echo "version=$VERSION" >> $GITHUB_OUTPUT
71+
echo "Building documentation for version: $VERSION"
72+
5573
- name: Build with mdBook
5674
run: |
5775
cd docs
5876
mdbook build
5977
78+
- name: Download existing GitHub Pages content
79+
run: |
80+
# IMPORTANT: GitHub Pages deployments completely replace the entire site with
81+
# the uploaded artifact. Without this preservation step, deploying a new version
82+
# (e.g., v0.4.0) would delete all previously published versions (e.g., v0.3.0, latest).
83+
# We fetch content from the gh-pages branch and merge it with the new version
84+
# to maintain a complete multi-version documentation site.
85+
echo "Attempting to download existing site content..."
86+
mkdir -p public
87+
88+
# Save current commit for returning later
89+
CURRENT_COMMIT=$(git rev-parse HEAD)
90+
91+
# Try to download existing site as a tarball from gh-pages branch
92+
if git ls-remote --heads origin gh-pages >/dev/null 2>&1; then
93+
echo "gh-pages branch exists, fetching existing content..."
94+
git fetch origin gh-pages:gh-pages || true
95+
git checkout gh-pages -- . 2>/dev/null || echo "No existing gh-pages content"
96+
# Move existing content to public if it exists
97+
if [ -d "wassette" ]; then
98+
cp -r wassette public/ || true
99+
fi
100+
# Return to original commit
101+
git checkout $CURRENT_COMMIT || echo "Could not return to original commit"
102+
else
103+
echo "gh-pages branch does not exist yet, starting fresh"
104+
fi
105+
106+
- name: Prepare versioned output
107+
run: |
108+
# Create directory structure for this version
109+
mkdir -p public/wassette/${{ steps.version.outputs.version }}
110+
111+
# Copy newly built docs to the version directory
112+
cp -r docs/book/* public/wassette/${{ steps.version.outputs.version }}/
113+
114+
# Create root redirect page (this should NOT be in docs source, only at GitHub Pages root)
115+
cat > public/wassette/index.html << 'EOF'
116+
<!DOCTYPE html>
117+
<html lang="en">
118+
<head>
119+
<meta charset="UTF-8">
120+
<meta http-equiv="refresh" content="0; url=latest/">
121+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
122+
<title>Redirecting to Wassette Documentation</title>
123+
<style>
124+
body {
125+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
126+
display: flex;
127+
justify-content: center;
128+
align-items: center;
129+
height: 100vh;
130+
margin: 0;
131+
background-color: #f5f5f5;
132+
}
133+
.message {
134+
text-align: center;
135+
padding: 2rem;
136+
background: white;
137+
border-radius: 8px;
138+
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
139+
}
140+
a {
141+
color: #4183c4;
142+
text-decoration: none;
143+
}
144+
a:hover {
145+
text-decoration: underline;
146+
}
147+
</style>
148+
</head>
149+
<body>
150+
<div class="message">
151+
<h1>Redirecting to Wassette Documentation</h1>
152+
<p>If you are not redirected automatically, <a href="latest/">click here</a>.</p>
153+
</div>
154+
</body>
155+
</html>
156+
EOF
157+
158+
# Load or create versions.json
159+
if [ -f "public/wassette/versions.json" ]; then
160+
echo "Using existing versions.json"
161+
cp public/wassette/versions.json versions.json.tmp
162+
else
163+
echo "Creating new versions.json"
164+
cp docs/versions.json versions.json.tmp
165+
fi
166+
167+
# Update versions.json with current version
168+
python3 << 'EOF'
169+
import json
170+
171+
version = "${{ steps.version.outputs.version }}"
172+
173+
try:
174+
with open("versions.json.tmp", "r") as f:
175+
data = json.load(f)
176+
except:
177+
data = {"versions": ["latest"], "latest": "latest"}
178+
179+
# Add current version if it's not already in the list
180+
if version not in data["versions"]:
181+
# Insert version after "latest" if it's a tag
182+
if version.startswith("v"):
183+
if "latest" in data["versions"]:
184+
idx = data["versions"].index("latest") + 1
185+
data["versions"].insert(idx, version)
186+
else:
187+
data["versions"].insert(0, version)
188+
else:
189+
# Ensure "latest" is first
190+
if "latest" not in data["versions"]:
191+
data["versions"].insert(0, "latest")
192+
193+
with open("public/wassette/versions.json", "w") as f:
194+
json.dump(data, f, indent=2)
195+
196+
print(f"Updated versions.json with version: {version}")
197+
print(f"All versions: {data['versions']}")
198+
EOF
199+
200+
echo "Current versions.json:"
201+
cat public/wassette/versions.json
202+
203+
echo ""
204+
echo "Directory structure:"
205+
ls -la public/wassette/
206+
60207
- name: Upload artifact
61208
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
62209
with:
63-
path: docs/book
210+
path: public/wassette
64211

65212
# Deployment job
66213
deploy:
@@ -69,7 +216,7 @@ jobs:
69216
url: ${{ steps.deployment.outputs.page_url }}
70217
runs-on: ubuntu-latest
71218
needs: build
72-
if: github.ref == 'refs/heads/main'
219+
if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
73220
steps:
74221
- name: Deploy to GitHub Pages
75222
id: deployment

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,8 @@
77

88
# mdbook output
99
/docs/book
10+
mdbook
11+
mdbook-mermaid
12+
13+
# typos binary
14+
typos

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
77
### Added
88

99
- Comprehensive installation guide page consolidating all installation methods (one-liner script, Homebrew, Nix, WinGet) organized by platform (Linux, macOS, Windows) with verification steps and troubleshooting sections
10+
- Multi-version documentation support with version dropdown, hosting at `/wassette/latest/` (main) and `/wassette/vX.Y/` (tags)
1011
- Automated release preparation and package manifest update workflows to eliminate manual version bump PRs ([#320](https://github.com/microsoft/wassette/pull/320))
1112

1213
### Changed
@@ -20,6 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
2021

2122
- `wassette secret set` now returns a clear error message when the component ID is not found, preventing silent failures and providing better user feedback
2223
- Fixed invalid `workflows` permission in dependabot-automerge workflow file that caused GitHub Actions validation error
24+
- Fixed Mermaid sequence diagram rendering in documentation by adding mdbook-mermaid preprocessor configuration
2325

2426
## [v0.3.0] - 2025-10-03
2527

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,14 @@ Congratulations! You've just run your first Wasm Component and taught your agent
8787

8888
https://github.com/user-attachments/assets/8e5a371c-ac72-406d-859c-03833ee83963
8989

90+
## Documentation
91+
92+
The [Wassette documentation][Documentation] supports multiple versions:
93+
- **[/latest/][Documentation]** - Built from the `main` branch (latest development)
94+
- **/vX.Y/** - Built from release tags (e.g., [v0.3.0](https://microsoft.github.io/wassette/v0.3.0/))
95+
96+
Use the version dropdown in the docs header to switch between versions while staying on the same page.
97+
9098
## Built-in Tools
9199

92100
Wassette comes with several built-in tools for managing components and their permissions. These tools are available immediately when you start the MCP server:

‎_typos.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
extend-exclude = [
33
"**/*.wit",
44
"**/*.wit.go",
5+
"**/mermaid.min.js",
6+
"**/mermaid-init.js",
57
]
68

79
[default.extend-words]

‎docs/book.toml‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ build-dir = "book"
1111
[preprocessor.tabs]
1212

1313
[output.html]
14-
additional-css = []
15-
additional-js = []
14+
additional-js = ["mermaid.min.js", "mermaid-init.js", "theme/version-picker.js"]
15+
additional-css = ["theme/version-picker.css"]
1616
smart-punctuation = true
1717
git-repository-url = "https://github.com/microsoft/wassette"
1818
edit-url-template = "https://github.com/microsoft/wassette/edit/main/docs/{path}"
@@ -27,3 +27,8 @@ boost-hierarchy = 1
2727
boost-paragraph = 1
2828
expand = true
2929
heading-split-level = 3
30+
31+
[preprocessor]
32+
33+
[preprocessor.mermaid]
34+
command = "mdbook-mermaid"

‎docs/mermaid-init.js‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
(() => {
2+
const darkThemes = ['ayu', 'navy', 'coal'];
3+
const lightThemes = ['light', 'rust'];
4+
5+
const classList = document.getElementsByTagName('html')[0].classList;
6+
7+
let lastThemeWasLight = true;
8+
for (const cssClass of classList) {
9+
if (darkThemes.includes(cssClass)) {
10+
lastThemeWasLight = false;
11+
break;
12+
}
13+
}
14+
15+
const theme = lastThemeWasLight ? 'default' : 'dark';
16+
mermaid.initialize({ startOnLoad: true, theme });
17+
18+
// Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
19+
20+
for (const darkTheme of darkThemes) {
21+
document.getElementById(darkTheme).addEventListener('click', () => {
22+
if (lastThemeWasLight) {
23+
window.location.reload();
24+
}
25+
});
26+
}
27+
28+
for (const lightTheme of lightThemes) {
29+
document.getElementById(lightTheme).addEventListener('click', () => {
30+
if (!lastThemeWasLight) {
31+
window.location.reload();
32+
}
33+
});
34+
}
35+
})();

‎docs/mermaid.min.js‎

Lines changed: 2186 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/theme/version-picker.css‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/* Version picker styling */
2+
.version-picker-container {
3+
display: flex;
4+
align-items: center;
5+
margin-right: 10px;
6+
}
7+
8+
.version-picker {
9+
padding: 4px 8px;
10+
border: 1px solid var(--theme-popup-border, #ccc);
11+
background: var(--theme-popup-bg, #fff);
12+
color: var(--theme-popup-fg, #000);
13+
border-radius: 4px;
14+
font-size: 0.9em;
15+
cursor: pointer;
16+
outline: none;
17+
transition: border-color 0.2s ease;
18+
}
19+
20+
.version-picker:hover {
21+
border-color: var(--links, #4183c4);
22+
}
23+
24+
.version-picker:focus {
25+
border-color: var(--links, #4183c4);
26+
box-shadow: 0 0 0 2px rgba(65, 131, 196, 0.2);
27+
}
28+
29+
/* Dark mode support */
30+
.coal .version-picker,
31+
.navy .version-picker,
32+
.ayu .version-picker {
33+
border-color: var(--theme-popup-border, #555);
34+
background: var(--theme-popup-bg, #3b3b3b);
35+
color: var(--theme-popup-fg, #fff);
36+
}

0 commit comments

Comments
 (0)