chore: migrate docs site from VitePress to Scalar Docs - #6
Open
sheepbox8646 wants to merge 1 commit into
Open
Conversation
Replace the VitePress setup with Scalar Docs, keeping the existing URL structure and information architecture unchanged. Self-written components are swapped for Scalar-provided ones: - DocsHome.vue + theme/style.css -> <PageLink> cards on both home pages - ::: tip/warning/danger containers -> <Callout type="..."> (10 pages renamed to .mdx and importing from scalar-mdx-components) - 88 Vue window.location.replace redirect stubs -> siteConfig.routing.redirects - locales + en.ts/zh.ts sidebars -> Scalar versions + built-in version selector - themeConfig.nav -> navigation.tabs, which also scopes the sidebar - themeConfig.footer -> siteConfig.footer (docs/footer.html) Local search, dark-mode toggle and the TOC now come from Scalar, so docs/.vitepress/ is removed along with the Vue dependency. Bilingual routing uses Scalar versions: the `default` version is served unprefixed and every other key becomes a path prefix, so `zh` reproduces the existing /zh/* URLs and Scalar renders the language switcher. Route keys inside the `zh` version are written without the /zh prefix. Internal links drop their .md suffixes to match the new routes. This also surfaced one pre-existing dead link (/zh/integrations/providers/tts/index), which VitePress had hidden behind ignoreDeadLinks: true. Verified with @scalar/cli: config validates, all 108 pages preprocess with no errors, sidebars generate 52 mirrored URLs per language, and there are no unresolved internal links, missing images, unrouted pages, or routes pointing at missing files. Hosting moves to Scalar, which has no static export, so the GitHub Pages workflow is replaced by check-config on PRs and project publish on tags. Going live still needs a CNAME for docs.memoh.ai pointing at dns.scalar.com, a Scalar Dashboard project, and a SCALAR_API_KEY secret. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the VitePress setup with Scalar Docs. URL structure and information architecture are unchanged.
Self-written components → Scalar components
DocsHome.vue+ 106-linetheme/style.css<PageLink>cards on both home pages::: tip / warning / dangercontainers<Callout type="info|warning|danger">window.location.replaceredirect stubssiteConfig.routing.redirectslocales+en.ts/zh.tssidebarsversions+ built-in version selectorthemeConfig.navnavigation.tabs(also scopes the sidebar)themeConfig.footersiteConfig.footer→docs/footer.htmldocs/.vitepress/is gone, along with the Vue dependency. Ten pages that use components were renamed to.mdxand import fromscalar-mdx-components.Bilingual routing
Scalar Docs has no first-class i18n, so both languages are wired up as versions. The CLI's
getVersionPathPrefixservesdefaultunprefixed and slugifies every other key into a path prefix — sozhreproduces the existing/zh/*URLs exactly, and Scalar renders the language switcher in the header. Route keys inside thezhversion are written without the/zhprefix; Scalar adds it.Verification
Ran the real build via
@scalar/cli, plus headless screenshots:check-configpasses; all 108 pages preprocess with no errors.mdsuffixes — 0 unresolved links, 0 missing images, every page on disk is routed and every route points at a real file/zh/integrations/providers/tts/index) that VitePress had hidden behindignoreDeadLinks: true— fixed here1. Hosting moves to Scalar. Scalar Docs is a hosted platform and the CLI has no static-export command, so the GitHub Pages deploy no longer applies. The workflow is replaced by
check-configon PRs andproject publishon tags. To actually deploy you still need to:docsCNAME atdns.scalar.com(DNS-only, no proxy)SCALAR_API_KEYto repository secretsUntil then the site will not be published.
2. Chrome text on Chinese pages stays English ("Search…", "On This Page", "Copy Page"). Scalar's localization only covers the API Reference UI; Docs has no per-version language setting. This is a platform limitation, not something configurable here.
🤖 Generated with Claude Code