ads-fe 0.0.1

package/skills/vitepress/references/advanced-ssr.md

@@ -0,0 +1,228 @@
+---
+name: vitepress-ssr-compatibility
+description: Server-side rendering compatibility, ClientOnly component, and handling browser-only code
+---
+
+# SSR Compatibility
+
+VitePress pre-renders pages on the server during build. All Vue code must be SSR-compatible.
+
+## The Rule
+
+Only access browser/DOM APIs in Vue lifecycle hooks:
+- `onMounted()`
+- `onBeforeMount()`
+
+```vue
+<script setup>
+import { onMounted, ref } from 'vue'
+
+const windowWidth = ref(0)
+
+onMounted(() => {
+  // Safe - runs only in browser
+  windowWidth.value = window.innerWidth
+})
+</script>
+```
+
+**Do NOT** access at top level:
+
+```vue
+<script setup>
+// WRONG - runs during SSR where window doesn't exist
+const width = window.innerWidth
+</script>
+```
+
+## ClientOnly Component
+
+Wrap non-SSR-friendly components:
+
+```vue
+<template>
+  <ClientOnly>
+    <BrowserOnlyComponent />
+  </ClientOnly>
+</template>
+```
+
+## Libraries That Access Browser on Import
+
+Some libraries access `window` or `document` when imported:
+
+### Dynamic Import in onMounted
+
+```vue
+<script setup>
+import { onMounted } from 'vue'
+
+onMounted(async () => {
+  const lib = await import('browser-only-library')
+  lib.doSomething()
+})
+</script>
+```
+
+### Conditional Import
+
+```ts
+if (!import.meta.env.SSR) {
+  const lib = await import('browser-only-library')
+  lib.doSomething()
+}
+```
+
+### In enhanceApp
+
+```ts
+// .vitepress/theme/index.ts
+export default {
+  async enhanceApp({ app }) {
+    if (!import.meta.env.SSR) {
+      const plugin = await import('browser-plugin')
+      app.use(plugin.default)
+    }
+  }
+}
+```
+
+## defineClientComponent
+
+Helper for components that access browser on import:
+
+```vue
+<script setup>
+import { defineClientComponent } from 'vitepress'
+
+const BrowserComponent = defineClientComponent(() => {
+  return import('browser-only-component')
+})
+</script>
+
+<template>
+  <BrowserComponent />
+</template>
+```
+
+With props and slots:
+
+```vue
+<script setup>
+import { ref, h } from 'vue'
+import { defineClientComponent } from 'vitepress'
+
+const componentRef = ref(null)
+
+const BrowserComponent = defineClientComponent(
+  () => import('browser-only-component'),
+  // Props passed to h()
+  [
+    { ref: componentRef, someProp: 'value' },
+    {
+      default: () => 'Default slot content',
+      header: () => h('div', 'Header slot')
+    }
+  ],
+  // Callback after component loads
+  () => {
+    console.log('Component loaded', componentRef.value)
+  }
+)
+</script>
+```
+
+## Teleports
+
+Teleport to body only with SSG:
+
+```vue
+<ClientOnly>
+  <Teleport to="body">
+    <div class="modal">Modal content</div>
+  </Teleport>
+</ClientOnly>
+```
+
+For other targets, use `postRender` hook:
+
+```ts
+// .vitepress/config.ts
+export default {
+  async postRender(context) {
+    // Inject teleport content into final HTML
+  }
+}
+```
+
+## Common SSR Errors
+
+### "window is not defined"
+
+Code accesses `window` at module level:
+
+```ts
+// BAD
+const width = window.innerWidth
+
+// GOOD
+let width: number
+onMounted(() => {
+  width = window.innerWidth
+})
+```
+
+### "document is not defined"
+
+Same issue with `document`:
+
+```ts
+// BAD
+const el = document.querySelector('#app')
+
+// GOOD
+onMounted(() => {
+  const el = document.querySelector('#app')
+})
+```
+
+### Hydration Mismatch
+
+Server and client render different content:
+
+```vue
+<!-- BAD - different on server vs client -->
+<div>{{ typeof window !== 'undefined' ? 'client' : 'server' }}</div>
+
+<!-- GOOD - consistent -->
+<ClientOnly>
+  <div>Client only content</div>
+</ClientOnly>
+```
+
+## Checking Environment
+
+```ts
+// In Vue component
+import.meta.env.SSR  // true on server, false on client
+
+// In VitePress
+import { inBrowser } from 'vitepress'
+if (inBrowser) {
+  // Client-only code
+}
+```
+
+## Key Points
+
+- Access browser APIs only in `onMounted` or `onBeforeMount`
+- Use `<ClientOnly>` for non-SSR components
+- Use `defineClientComponent` for libraries that access browser on import
+- Check `import.meta.env.SSR` for environment-specific code
+- Teleport to body only, or use `postRender` hook
+- Consistent rendering prevents hydration mismatches
+
+<!--
+Source references:
+- https://vitepress.dev/guide/ssr-compat
+-->

package/skills/vitepress/references/core-cli.md

@@ -0,0 +1,119 @@
+---
+name: vitepress-cli
+description: Command-line interface for development, building, and previewing VitePress sites
+---
+
+# CLI Commands
+
+VitePress provides four main commands: `dev`, `build`, `preview`, and `init`.
+
+## Development Server
+
+Start the dev server with hot module replacement:
+
+```bash
+# In current directory (dev command is optional)
+vitepress
+
+# Or explicitly
+vitepress dev
+
+# With project in subdirectory
+vitepress dev docs
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--open [path]` | Open browser on startup |
+| `--port <port>` | Specify port number |
+| `--base <path>` | Override base URL |
+| `--cors` | Enable CORS |
+| `--strictPort` | Exit if port is in use |
+| `--force` | Ignore cache and re-bundle |
+
+```bash
+vitepress dev docs --port 3000 --open
+```
+
+## Production Build
+
+Build static files for production:
+
+```bash
+vitepress build docs
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--base <path>` | Override base URL |
+| `--target <target>` | Transpile target (default: `modules`) |
+| `--outDir <dir>` | Output directory (relative to cwd) |
+| `--assetsInlineLimit <n>` | Asset inline threshold in bytes |
+| `--mpa` | Build in MPA mode (no client hydration) |
+
+```bash
+vitepress build docs --outDir dist
+```
+
+## Preview Production Build
+
+Locally preview the production build:
+
+```bash
+vitepress preview docs
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--port <port>` | Specify port number |
+| `--base <path>` | Override base URL |
+
+```bash
+vitepress preview docs --port 4173
+```
+
+## Initialize Project
+
+Start the setup wizard:
+
+```bash
+vitepress init
+```
+
+This creates the basic file structure:
+- `.vitepress/config.js` - Configuration
+- `index.md` - Home page
+- Optional example pages
+
+## Package.json Scripts
+
+Typical scripts configuration:
+
+```json
+{
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}
+```
+
+## Key Points
+
+- Dev server runs at `http://localhost:5173` by default
+- Preview server runs at `http://localhost:4173`
+- Production output goes to `.vitepress/dist` by default
+- The `docs` argument specifies the project root directory
+- Use `--base` to override base path without modifying config
+
+<!--
+Source references:
+- https://vitepress.dev/reference/cli
+-->

package/skills/vitepress/references/core-config.md

@@ -0,0 +1,189 @@
+---
+name: vitepress-configuration
+description: Config file setup, defineConfig helper, site metadata, and build options
+---
+
+# Configuration
+
+VitePress configuration is defined in `.vitepress/config.[js|ts|mjs|mts]`. Use `defineConfig` for TypeScript intellisense.
+
+## Basic Config
+
+```ts
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  // Site metadata
+  title: 'My Docs',
+  description: 'Documentation site',
+  lang: 'en-US',
+  
+  // URL base path (for GitHub Pages: '/repo-name/')
+  base: '/',
+  
+  // Theme configuration
+  themeConfig: {
+    // See theme-config.md
+  }
+})
+```
+
+## Site Metadata
+
+```ts
+export default defineConfig({
+  title: 'VitePress',           // Displayed in nav, used in page titles
+  titleTemplate: ':title - Docs', // Page title format (:title = h1)
+  description: 'Site description', // Meta description
+  lang: 'en-US',                 // HTML lang attribute
+  
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    ['meta', { name: 'theme-color', content: '#5f67ee' }],
+    ['script', { async: '', src: 'https://analytics.example.com/script.js' }]
+  ]
+})
+```
+
+## Build Options
+
+```ts
+export default defineConfig({
+  // Source files directory (relative to project root)
+  srcDir: './src',
+  
+  // Exclude patterns from source
+  srcExclude: ['**/README.md', '**/TODO.md'],
+  
+  // Output directory
+  outDir: './.vitepress/dist',
+  
+  // Cache directory
+  cacheDir: './.vitepress/cache',
+  
+  // Clean URLs without .html extension (requires server support)
+  cleanUrls: true,
+  
+  // Ignore dead links during build
+  ignoreDeadLinks: true,
+  // Or specific patterns:
+  ignoreDeadLinks: ['/playground', /^https?:\/\/localhost/],
+  
+  // Get last updated timestamp from git
+  lastUpdated: true
+})
+```
+
+## Route Rewrites
+
+Map source paths to different output paths:
+
+```ts
+export default defineConfig({
+  rewrites: {
+    // Static mapping
+    'packages/pkg-a/src/index.md': 'pkg-a/index.md',
+    
+    // Dynamic parameters
+    'packages/:pkg/src/:slug*': ':pkg/:slug*'
+  }
+})
+```
+
+## Appearance (Dark Mode)
+
+```ts
+export default defineConfig({
+  appearance: true,           // Enable toggle (default)
+  appearance: 'dark',         // Dark by default
+  appearance: 'force-dark',   // Always dark, no toggle
+  appearance: 'force-auto',   // Always follow system preference
+  appearance: false           // Disable dark mode
+})
+```
+
+## Vite & Vue Configuration
+
+```ts
+export default defineConfig({
+  // Pass options to Vite
+  vite: {
+    plugins: [],
+    resolve: { alias: {} },
+    css: { preprocessorOptions: {} }
+  },
+  
+  // Pass options to @vitejs/plugin-vue
+  vue: {
+    template: { compilerOptions: {} }
+  },
+  
+  // Configure markdown-it
+  markdown: {
+    lineNumbers: true,
+    toc: { level: [1, 2, 3] },
+    math: true, // Requires markdown-it-mathjax3
+    container: {
+      tipLabel: 'TIP',
+      warningLabel: 'WARNING',
+      dangerLabel: 'DANGER'
+    }
+  }
+})
+```
+
+## Build Hooks
+
+```ts
+export default defineConfig({
+  // Transform page data
+  transformPageData(pageData, { siteConfig }) {
+    pageData.frontmatter.head ??= []
+    pageData.frontmatter.head.push([
+      'meta', { name: 'og:title', content: pageData.title }
+    ])
+  },
+  
+  // Transform head before generating each page
+  async transformHead(context) {
+    return [['meta', { name: 'custom', content: context.page }]]
+  },
+  
+  // After build completes
+  async buildEnd(siteConfig) {
+    // Generate sitemap, RSS, etc.
+  }
+})
+```
+
+## Dynamic Config
+
+For async configuration:
+
+```ts
+export default async () => {
+  const data = await fetch('https://api.example.com/data').then(r => r.json())
+  
+  return defineConfig({
+    title: data.title,
+    themeConfig: {
+      sidebar: data.sidebar
+    }
+  })
+}
+```
+
+## Key Points
+
+- Config file supports `.js`, `.ts`, `.mjs`, `.mts` extensions
+- Use `defineConfig` for TypeScript support
+- `base` must start and end with `/` for sub-path deployments
+- `srcDir` separates source files from project root
+- Build hooks enable custom transformations and post-processing
+
+<!--
+Source references:
+- https://vitepress.dev/reference/site-config
+- https://vitepress.dev/guide/getting-started
+-->