aico-cli 2.1.1 → 2.1.23

package/templates/skills/vitepress/references/theme-config.md

@@ -0,0 +1,315 @@
+---
+name: vitepress-theme-configuration
+description: Default theme configuration for navigation, sidebar, search, social links, and footer
+---
+
+# Theme Configuration
+
+Configure the default theme via `themeConfig` in your VitePress config.
+
+## Navigation
+
+```ts
+export default {
+  themeConfig: {
+    // Site title in nav (overrides config.title)
+    siteTitle: 'My Docs',
+    siteTitle: false,  // Hide title
+    
+    // Logo
+    logo: '/logo.svg',
+    logo: { light: '/light-logo.svg', dark: '/dark-logo.svg', alt: 'Logo' },
+    
+    // Nav links
+    nav: [
+      { text: 'Guide', link: '/guide/' },
+      { text: 'API', link: '/api/' },
+      { text: 'GitHub', link: 'https://github.com/...' }
+    ]
+  }
+}
+```
+
+### Dropdown Menu
+
+```ts
+nav: [
+  {
+    text: 'Dropdown',
+    items: [
+      { text: 'Item A', link: '/item-a' },
+      { text: 'Item B', link: '/item-b' }
+    ]
+  },
+  // With sections
+  {
+    text: 'Versions',
+    items: [
+      {
+        text: 'v2.x',
+        items: [
+          { text: 'v2.0', link: '/v2/' },
+          { text: 'v2.1', link: '/v2.1/' }
+        ]
+      }
+    ]
+  }
+]
+```
+
+### Active Match
+
+Control when nav item shows as active:
+
+```ts
+nav: [
+  {
+    text: 'Guide',
+    link: '/guide/',
+    activeMatch: '/guide/'  // Regex pattern
+  }
+]
+```
+
+## Sidebar
+
+### Simple Sidebar
+
+```ts
+sidebar: [
+  {
+    text: 'Guide',
+    items: [
+      { text: 'Introduction', link: '/guide/' },
+      { text: 'Getting Started', link: '/guide/getting-started' }
+    ]
+  }
+]
+```
+
+### Multiple Sidebars
+
+Different sidebar per section:
+
+```ts
+sidebar: {
+  '/guide/': [
+    {
+      text: 'Guide',
+      items: [
+        { text: 'Introduction', link: '/guide/' },
+        { text: 'Getting Started', link: '/guide/getting-started' }
+      ]
+    }
+  ],
+  '/api/': [
+    {
+      text: 'API Reference',
+      items: [
+        { text: 'Config', link: '/api/config' },
+        { text: 'Methods', link: '/api/methods' }
+      ]
+    }
+  ]
+}
+```
+
+### Collapsible Groups
+
+```ts
+sidebar: [
+  {
+    text: 'Section A',
+    collapsed: false,  // Open by default, can collapse
+    items: [...]
+  },
+  {
+    text: 'Section B',
+    collapsed: true,   // Collapsed by default
+    items: [...]
+  }
+]
+```
+
+### Base Path
+
+Simplify links with common base:
+
+```ts
+sidebar: {
+  '/guide/': {
+    base: '/guide/',
+    items: [
+      { text: 'Intro', link: 'intro' },        // /guide/intro
+      { text: 'Setup', link: 'getting-started' } // /guide/getting-started
+    ]
+  }
+}
+```
+
+## Search
+
+### Local Search
+
+```ts
+themeConfig: {
+  search: {
+    provider: 'local'
+  }
+}
+```
+
+With options:
+
+```ts
+search: {
+  provider: 'local',
+  options: {
+    miniSearch: {
+      searchOptions: {
+        fuzzy: 0.2,
+        prefix: true
+      }
+    }
+  }
+}
+```
+
+### Algolia DocSearch
+
+```ts
+search: {
+  provider: 'algolia',
+  options: {
+    appId: 'YOUR_APP_ID',
+    apiKey: 'YOUR_API_KEY',
+    indexName: 'YOUR_INDEX_NAME'
+  }
+}
+```
+
+## Social Links
+
+```ts
+socialLinks: [
+  { icon: 'github', link: 'https://github.com/...' },
+  { icon: 'twitter', link: 'https://twitter.com/...' },
+  { icon: 'discord', link: 'https://discord.gg/...' },
+  // Custom SVG
+  {
+    icon: { svg: '<svg>...</svg>' },
+    link: 'https://...',
+    ariaLabel: 'Custom Link'
+  }
+]
+```
+
+## Footer
+
+```ts
+footer: {
+  message: 'Released under the MIT License.',
+  copyright: 'Copyright © 2024 My Project'
+}
+```
+
+Footer only displays on pages without sidebar.
+
+## Edit Link
+
+```ts
+editLink: {
+  pattern: 'https://github.com/org/repo/edit/main/docs/:path',
+  text: 'Edit this page on GitHub'
+}
+```
+
+`:path` is replaced with the page's source file path.
+
+## Last Updated
+
+Enable in site config:
+
+```ts
+export default {
+  lastUpdated: true  // Get timestamp from git
+}
+```
+
+Customize display:
+
+```ts
+themeConfig: {
+  lastUpdated: {
+    text: 'Updated at',
+    formatOptions: {
+      dateStyle: 'full',
+      timeStyle: 'medium'
+    }
+  }
+}
+```
+
+## Outline (Table of Contents)
+
+```ts
+outline: {
+  level: [2, 3],      // Which heading levels to show
+  label: 'On this page'
+}
+```
+
+Or just the level:
+
+```ts
+outline: 'deep'  // Same as [2, 6]
+outline: 2       // Only h2
+outline: [2, 4]  // h2 through h4
+```
+
+## Doc Footer Navigation
+
+```ts
+docFooter: {
+  prev: 'Previous page',
+  next: 'Next page'
+}
+// Or disable:
+docFooter: {
+  prev: false,
+  next: false
+}
+```
+
+## External Link Icon
+
+```ts
+externalLinkIcon: true  // Show icon on external links
+```
+
+## Appearance Toggle Labels
+
+```ts
+darkModeSwitchLabel: 'Appearance',
+lightModeSwitchTitle: 'Switch to light theme',
+darkModeSwitchTitle: 'Switch to dark theme',
+sidebarMenuLabel: 'Menu',
+returnToTopLabel: 'Return to top'
+```
+
+## Key Points
+
+- `nav` defines top navigation links
+- `sidebar` can be array (single) or object (multiple sidebars)
+- Use `collapsed` for collapsible sidebar sections
+- Local search works out of the box
+- `editLink.pattern` uses `:path` placeholder
+- Enable `lastUpdated` in site config, customize in themeConfig
+
+<!--
+Source references:
+- https://vitepress.dev/reference/default-theme-config
+- https://vitepress.dev/reference/default-theme-nav
+- https://vitepress.dev/reference/default-theme-sidebar
+- https://vitepress.dev/reference/default-theme-search
+-->

package/templates/skills/vitepress/references/theme-custom.md

@@ -0,0 +1,269 @@
+---
+name: vitepress-custom-themes
+description: Building custom themes from scratch with the theme interface, Layout component, and enhanceApp
+---
+
+# Custom Themes
+
+Build a theme from scratch when the default theme doesn't fit your needs.
+
+## Theme Entry
+
+Create `.vitepress/theme/index.ts`:
+
+```ts
+// .vitepress/theme/index.ts
+import Layout from './Layout.vue'
+
+export default {
+  Layout,
+  enhanceApp({ app, router, siteData }) {
+    // Register global components, plugins, etc.
+  }
+}
+```
+
+## Theme Interface
+
+```ts
+interface Theme {
+  // Required: Root layout component
+  Layout: Component
+  
+  // Optional: Enhance Vue app instance
+  enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
+  
+  // Optional: Extend another theme
+  extends?: Theme
+}
+
+interface EnhanceAppContext {
+  app: App              // Vue app instance
+  router: Router        // VitePress router
+  siteData: Ref<SiteData>  // Site-level metadata
+}
+```
+
+## Basic Layout
+
+The Layout component must render `<Content />` for markdown:
+
+```vue
+<!-- .vitepress/theme/Layout.vue -->
+<script setup>
+import { useData } from 'vitepress'
+const { page, frontmatter } = useData()
+</script>
+
+<template>
+  <div class="layout">
+    <header>
+      <nav>My Site</nav>
+    </header>
+    
+    <main>
+      <div v-if="page.isNotFound">
+        <h1>404 - Page Not Found</h1>
+      </div>
+      
+      <div v-else-if="frontmatter.layout === 'home'">
+        <h1>Welcome!</h1>
+      </div>
+      
+      <article v-else>
+        <Content />
+      </article>
+    </main>
+    
+    <footer>
+      <p>© 2024 My Site</p>
+    </footer>
+  </div>
+</template>
+```
+
+## Runtime API
+
+Access VitePress data in your theme:
+
+```vue
+<script setup>
+import { useData, useRoute, useRouter } from 'vitepress'
+
+// Page and site data
+const { 
+  site,        // Site config (title, description, etc.)
+  theme,       // Theme config
+  page,        // Current page data
+  frontmatter, // Current page frontmatter
+  title,       // Page title
+  description, // Page description
+  lang,        // Current language
+  isDark,      // Dark mode state
+  params       // Dynamic route params
+} = useData()
+
+// Routing
+const route = useRoute()
+const router = useRouter()
+
+// Navigate programmatically
+const goToGuide = () => router.go('/guide/')
+</script>
+```
+
+## Built-in Components
+
+```vue
+<script setup>
+import { Content } from 'vitepress'
+</script>
+
+<template>
+  <!-- Renders markdown content -->
+  <Content />
+  
+  <!-- Renders slot only on client (SSR-safe) -->
+  <ClientOnly>
+    <NonSSRComponent />
+  </ClientOnly>
+</template>
+```
+
+## Extend Another Theme
+
+Build on top of default theme or any other:
+
+```ts
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    // Your customizations
+  }
+}
+```
+
+## Register Plugins and Components
+
+```ts
+// .vitepress/theme/index.ts
+import Layout from './Layout.vue'
+import GlobalComponent from './GlobalComponent.vue'
+
+export default {
+  Layout,
+  enhanceApp({ app }) {
+    // Register global component
+    app.component('GlobalComponent', GlobalComponent)
+    
+    // Register plugin
+    app.use(MyPlugin)
+    
+    // Provide/inject
+    app.provide('key', value)
+  }
+}
+```
+
+## Async enhanceApp
+
+For plugins that need async initialization:
+
+```ts
+export default {
+  Layout,
+  async enhanceApp({ app }) {
+    if (!import.meta.env.SSR) {
+      // Client-only plugin
+      const plugin = await import('browser-only-plugin')
+      app.use(plugin.default)
+    }
+  }
+}
+```
+
+## Theme-Aware Layout
+
+Handle different page layouts:
+
+```vue
+<script setup>
+import { useData } from 'vitepress'
+import Home from './Home.vue'
+import Doc from './Doc.vue'
+import Page from './Page.vue'
+import NotFound from './NotFound.vue'
+
+const { page, frontmatter } = useData()
+</script>
+
+<template>
+  <NotFound v-if="page.isNotFound" />
+  <Home v-else-if="frontmatter.layout === 'home'" />
+  <Page v-else-if="frontmatter.layout === 'page'" />
+  <Doc v-else />
+</template>
+```
+
+## Distributing a Theme
+
+As npm package:
+
+```ts
+// my-theme/index.ts
+import Layout from './Layout.vue'
+export default { Layout }
+
+// Export types for config
+export type { ThemeConfig } from './types'
+```
+
+Consumer usage:
+
+```ts
+// .vitepress/theme/index.ts
+import Theme from 'my-vitepress-theme'
+
+export default Theme
+
+// Or extend it
+export default {
+  extends: Theme,
+  enhanceApp({ app }) {
+    // Additional customization
+  }
+}
+```
+
+## Theme Config Types
+
+For custom theme config types:
+
+```ts
+// .vitepress/config.ts
+import { defineConfigWithTheme } from 'vitepress'
+import type { ThemeConfig } from 'my-theme'
+
+export default defineConfigWithTheme<ThemeConfig>({
+  themeConfig: {
+    // Type-checked theme config
+  }
+})
+```
+
+## Key Points
+
+- Theme must export `Layout` component
+- `<Content />` renders the markdown content
+- Use `useData()` to access page/site data
+- `enhanceApp` runs on both server and client
+- Check `import.meta.env.SSR` for client-only code
+- Use `extends` to build on existing themes
+
+<!--
+Source references:
+- https://vitepress.dev/guide/custom-theme
+-->