ads-fe 0.0.1

package/skills/vitepress/references/recipes-deploy.md

@@ -0,0 +1,240 @@
+---
+name: vitepress-deployment
+description: Deploying VitePress sites to various platforms including GitHub Pages, Netlify, Vercel, and more
+---
+
+# Deployment
+
+Deploy VitePress static sites to various hosting platforms.
+
+## Build and Preview
+
+```bash
+# Build production files
+npm run docs:build
+
+# Preview locally
+npm run docs:preview
+```
+
+Output is in `.vitepress/dist` by default.
+
+## Setting Base Path
+
+For sub-path deployment (e.g., `https://user.github.io/repo/`):
+
+```ts
+// .vitepress/config.ts
+export default {
+  base: '/repo/'
+}
+```
+
+## GitHub Pages
+
+Create `.github/workflows/deploy.yml`:
+
+```yaml
+name: Deploy VitePress
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run docs:build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment
+```
+
+Enable GitHub Pages in repository settings → Pages → Source: "GitHub Actions".
+
+For pnpm, add before setup-node:
+
+```yaml
+- uses: pnpm/action-setup@v4
+  with:
+    version: 9
+```
+
+## Netlify / Vercel / Cloudflare Pages
+
+Configure in dashboard:
+
+| Setting | Value |
+|---------|-------|
+| Build Command | `npm run docs:build` |
+| Output Directory | `docs/.vitepress/dist` |
+| Node Version | `20` (or above) |
+
+**Warning:** Don't enable "Auto Minify" for HTML - it removes Vue hydration comments.
+
+### Vercel Configuration
+
+For clean URLs, add `vercel.json`:
+
+```json
+{
+  "cleanUrls": true
+}
+```
+
+## GitLab Pages
+
+Create `.gitlab-ci.yml`:
+
+```yaml
+image: node:18
+
+pages:
+  cache:
+    paths:
+      - node_modules/
+  script:
+    - npm install
+    - npm run docs:build
+  artifacts:
+    paths:
+      - public
+  only:
+    - main
+```
+
+Set `outDir: '../public'` in config if needed.
+
+## Firebase
+
+```json
+// firebase.json
+{
+  "hosting": {
+    "public": "docs/.vitepress/dist",
+    "ignore": []
+  }
+}
+```
+
+```bash
+npm run docs:build
+firebase deploy
+```
+
+## Nginx
+
+```nginx
+server {
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml;
+
+    listen 80;
+    server_name _;
+    index index.html;
+
+    location / {
+        root /app;
+        try_files $uri $uri.html $uri/ =404;
+        error_page 404 /404.html;
+        error_page 403 /404.html;
+    }
+
+    # Cache hashed assets
+    location ~* ^/assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}
+```
+
+**Important:** Don't default to `index.html` like SPAs - use `$uri.html` for clean URLs.
+
+## HTTP Cache Headers
+
+For hashed assets (immutable):
+
+```
+Cache-Control: max-age=31536000, immutable
+```
+
+### Netlify `_headers`
+
+Place in `docs/public/_headers`:
+
+```
+/assets/*
+  cache-control: max-age=31536000
+  cache-control: immutable
+```
+
+### Vercel `vercel.json`
+
+```json
+{
+  "headers": [
+    {
+      "source": "/assets/(.*)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "max-age=31536000, immutable"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Other Platforms
+
+| Platform | Guide |
+|----------|-------|
+| Azure Static Web Apps | Set `app_location: /`, `output_location: docs/.vitepress/dist` |
+| Surge | `npx surge docs/.vitepress/dist` |
+| Heroku | Use `heroku-buildpack-static` |
+| Render | Build: `npm run docs:build`, Publish: `docs/.vitepress/dist` |
+| Kinsta | Follow [Kinsta docs](https://kinsta.com/docs/vitepress-static-site-example/) |
+
+## Key Points
+
+- Set `base` for sub-path deployments
+- GitHub Pages requires workflow file and enabling Pages in settings
+- Most platforms: Build `npm run docs:build`, output `docs/.vitepress/dist`
+- Don't enable HTML minification (breaks hydration)
+- Cache `/assets/*` with immutable headers
+- For clean URLs on Nginx, use `try_files $uri $uri.html $uri/ =404`
+
+<!--
+Source references:
+- https://vitepress.dev/guide/deploy
+-->

package/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
+-->