القائمة
Use when changing VuePress Theme Hope config, routing, navbar, sidebar, theme options, plugins, homepage layout, or documentation site behavior in ai-docs
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when planning ai-docs sections, routes, page hierarchy, navigation, sidebar grouping, redirects, indexes, or documentation taxonomy before writing pages
Use when adding Theme Hope Markdown extensions, tabs, code tabs, demos, components, images, include snippets, charts, math, PlantUML, GFM, or advanced Markdown syntax in ai-docs
Use when ai-docs content depends on external facts, official documentation, product behavior, CLI flags, package versions, Theme Hope capabilities, or claims that may change
Use when changing ai-docs Theme Hope styles, SCSS variables, colors, fonts, layout widths, static assets, logos, favicons, images, videos, or public files
Use when ai-docs documentation, VuePress Theme Hope config, navigation, sidebar, Markdown enhancements, assets, styles, or published routes may be complete or failing
Use when creating, rewriting, expanding, localizing, or reorganizing Markdown documentation pages in the ai-docs VuePress site
| name | ai-docs-theme-hope |
| description | Use when changing VuePress Theme Hope config, routing, navbar, sidebar, theme options, plugins, homepage layout, or documentation site behavior in ai-docs |
本项目是 VuePress 2 + vuepress-theme-hope 文档站。Theme Hope 的能力分布在站点配置、主题配置、导航、侧边栏、页面 frontmatter、Markdown 增强、插件和样式文件中。改动时必须尊重这些作用域，不要把所有配置塞进一个文件。
src/.vuepress/**, package.json, or docs scripts.config.ts, theme.ts, frontmatter, styles, or page Markdown.Use ai-docs-information-architecture before changing section structure. Use ai-docs-markdown-enhancements before enabling or using advanced Markdown syntax. Use ai-docs-style-assets before changing styles or static assets.
| Path | Purpose |
|---|---|
src | VuePress docs root; only Markdown and assets under this tree become site source. |
src/README.md | Site homepage, route /. |
src/<dir>/README.md | Section index, route /<dir>/. |
src/.vuepress/config.ts | VuePress core site config via defineUserConfig. |
src/.vuepress/theme.ts | Theme Hope config via hopeTheme. |
src/.vuepress/navbar.ts | Navbar config, imported from theme.ts. |
src/.vuepress/sidebar.ts | Sidebar config, imported from theme.ts. |
src/.vuepress/styles | Theme variables and global style overrides. |
src/.vuepress/public | Static files served from site root. |
.js local import suffixes.base, lang, title, description, and external VuePress plugins in config.ts.hostname, author, license, favicon, logo, repo, docsDir, navbar, sidebar, markdown, plugins, footer, and metaLocales in theme.ts.title, description, icon, category, tag, navbar: false, sidebar: false, index, order, dir, prev, and next in frontmatter.navbar(...) and sidebar(...) helpers from vuepress-theme-hope..cache, .temp, or dist.plugins unless official docs say so. Configure theme-bundled plugins under plugins.<shortName> in theme.ts.| Option | Rule |
|---|---|
hostname | Required for deployed site metadata; include full protocol such as https://example.com. |
author | Set globally when page info, copyright, or feed-like metadata relies on author data. |
license | Use when footer or page metadata should show license. |
favicon | Prefer files in src/.vuepress/public, referenced by root path such as /favicon.ico. |
logo / logoDark | Use absolute site path from public for local logo assets. |
hotReload | Enable only when you accept slower dev reloads for structured sidebar, git info, categories, tags, or blog recalculation. |
| Task | Edit |
|---|---|
| Add page in an existing section | Add src/<section>/<page>.md with order. |
| Add a section landing page | Add src/<section>/README.md, then update navbar/sidebar if it is top-level. |
| Add top-level navbar item | Edit src/.vuepress/navbar.ts. |
| Add top-level sidebar group | Edit src/.vuepress/sidebar.ts. |
| Change ordering in structure sidebar | Edit page frontmatter order, not generated output. |
| Hide page from structure sidebar/catalog | Set index: false in page frontmatter. |
| Hide sidebar on one page | Set sidebar: false in page frontmatter. |
| Add a folder group title/icon | Add or update that folder's README.md frontmatter dir. |
Current sidebar uses children: "structure" for getting-started/; Theme Hope reads files and frontmatter. Use README.md frontmatter dir only for folder groups.
| File | Route |
|---|---|
src/README.md | / |
src/foo.md | /foo.html |
src/foo/README.md | /foo/ |
src/foo/bar.md | /foo/bar.html |
Use relative links in Markdown; use root-relative links in navbar/sidebar.
| Pattern | Use When |
|---|---|
String item "/guide/" | Page frontmatter already has good title and icon. |
Object item { text, icon, link } | Nav text must be shorter or different from page title. |
Dropdown { text, icon, prefix, children } | Many related links should be grouped. |
activeMatch | Default active matching is too broad or too narrow. |
navbar: false | Hide navbar globally in theme options or for one page in frontmatter. |
Do not add many top-level navbar items. Put secondary content into dropdowns or sidebars.
| Pattern | Use When |
|---|---|
| Array sidebar | Small fixed set of pages. |
| Object sidebar | Different route prefixes need different sidebars. Put more specific keys before /. |
children: "structure" | Files under a prefix should generate sidebar from file tree and frontmatter. |
sidebar: "structure" | Entire site should be generated from file structure. Use cautiously on large sites. |
dir frontmatter | Folder grouping needs title, icon, order, collapse state, link behavior, or index behavior. |
sidebarSorter | Default ["readme", "order", "title", "filename"] sorting is insufficient. |
README.md is special in structured sidebar: unless excluded by index: false or used as a group link, it appears first.
| Current Plugin Area | Project Rule |
|---|---|
components | Register Theme Hope components before using them in Markdown, e.g. Badge, VPCard. |
icon | Current prefix is fa6-solid:; page icon values usually omit the prefix. |
comment | Treat current Giscus config as demo-like unless project owner provides real repo/category. |
| Search | Enable intentionally; search plugins usually surface automatically in navbar after configured. |
| Blog/feed/PWA/copyright | Add dependency and production-ready config deliberately, not by copying commented examples. |
src/README.md controls the homepage.| Mistake | Fix |
|---|---|
Editing src/.vuepress/dist | Edit source, then rebuild. |
Adding .md suffix inconsistently in nav/sidebar | Follow existing style; routes ending in / infer README.md. |
| Forgetting fallback sidebar order | Put more specific sidebar object keys before /. |
Adding page but no order | Add order to control structure sidebar. |
| Enabling markdown feature without dependency | Install/configure the required package or avoid the feature. |
Editing config.ts for a theme option | Move the option into hopeTheme(...) in theme.ts. |
| Calling bundled plugin manually | Configure it under plugins in theme options. |
| Expecting dev sidebar to update after Markdown frontmatter changes | Restart dev server or enable hotReload knowingly. |