MicrosoftKnown publishermicrosoft/vscode-documentdb/.github/skills/previewing-docs-site/SKILL.md

previewing-docs-site

Skill33 starsChanged 5 days agoMITView on GitHub

Builds and serves the documentation site (docs/, GitHub Pages with Just the Docs) locally so changes can be reviewed before they ship. Use when asked to preview, render, check or review the docs site, the user manual, release notes or the landing page, or to verify styling, images, light and dark mode, or the sidebar.

In this repository17 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- detecting-accessibility-issuesSkill
- backportSkill
- documentation-screenshotsSkill
- error-translationSkill
- flagging-fresh-dependenciesSkill
- fluentuiSkill
- leadSkill
- prepare-pull-requestSkill
- react-webview-architectureSkill
- review-external-prSkill
- skill-creatorSkill
- telemetry-instrumentationSkill
- tree-cluster-architectureSkill
- ux-pr-reviewSkill
- webview-trpc-messagingSkill
- writing-release-notesSkill

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
When an agent runs it, start it as a detached background process and poll the URL until it returns 200 before opening pages.
line 27
Very specific:
Theme-aware images: Every <picture> should swap to its _dark source in dark mode.
line 48
Very specific:
Excluded content: Only index.md, user-manual/ and release-notes/ are published.
line 50

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Previewing the Docs Site

The site is built by GitHub Pages from docs/ with the Just the Docs remote theme. There are no hosted PR previews, so review changes with a local build. Background and site structure: docs/ai-and-plans/features/docs-site/README.md.

Quick start (Windows)

.github/skills/previewing-docs-site/scripts/preview.ps1            # port 4000
.github/skills/previewing-docs-site/scripts/preview.ps1 -Port 4001 # second checkout

Open http://127.0.0.1:4000/vscode-documentdb/ (note the base URL) once the log says Server running. The first build downloads the theme and takes about 2 minutes; later edits rebuild automatically.

The script keeps everything outside the repository (Gemfile copy, Gemfile.lock, _site) in %TEMP%\vscode-documentdb-docs-preview, installs gems on first use, and fixes the --source path casing (see Pitfalls).

When an agent runs it, start it as a detached background process and poll the URL until it returns 200 before opening pages.

Prerequisites

Ruby with the DevKit: winget install RubyInstallerTeam.RubyWithDevKit.3.3 (the script also looks in C:\Ruby33-x64\bin)
Network access for the first build (gems and the remote theme)

macOS and Linux

mkdir -p /tmp/docs-preview && cp .github/skills/previewing-docs-site/scripts/Gemfile /tmp/docs-preview/
cd /tmp/docs-preview && bundle install
bundle exec jekyll serve --source "$OLDPWD/docs" --destination ./_site --livereload

What to check

Light and dark mode. The site follows the OS color scheme. In a browser, toggle the OS setting, or with Playwright use page.emulateMedia({ colorScheme: 'dark' }).
Theme-aware images. Every <picture> should swap to its _dark source in dark mode.
Sidebar and "On this page". New pages appear only after a restart (see Pitfalls).
Excluded content. Only index.md, user-manual/ and release-notes/ are published; other docs/ content must be listed under exclude in _config.yml.

Pitfalls

Symptom	Cause and fix
Custom styles missing, no error	`--source` casing differs from the disk (e.g. `C:\local` vs `C:\Local`), so `docs/_sass` is dropped. Use the script.
New page or `_config.yml` change not visible	The sidebar is cached (`jekyll-include-cache`) and config is read once. Stop the server and start it again.
`/` returns 404	The site lives under `/vscode-documentdb/`.
Port already in use	Another preview is running. Use `-Port 4001`, or stop the old `ruby.exe` by its process ID.
Build works locally but not on GitHub	Pages builds `gh-pages` itself (legacy build), so only plugins listed on pages.github.com/versions work. Keep the Gemfile on `github-pages`.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free