ads-fe 0.0.1

package/skills/vitepress/references/features-data-loading.md

@@ -0,0 +1,220 @@
+---
+name: vitepress-data-loading
+description: Build-time data loaders for fetching remote data or processing local files
+---
+
+# Data Loading
+
+VitePress data loaders run at build time to load arbitrary data that's serialized as JSON in the client bundle.
+
+## Basic Usage
+
+Create a file ending with `.data.js` or `.data.ts`:
+
+```ts
+// example.data.ts
+export default {
+  load() {
+    return {
+      hello: 'world',
+      timestamp: Date.now()
+    }
+  }
+}
+```
+
+Import the `data` named export:
+
+```vue
+<script setup>
+import { data } from './example.data.ts'
+</script>
+
+<template>
+  <pre>{{ data }}</pre>
+</template>
+```
+
+## Async Data
+
+Fetch remote data:
+
+```ts
+// api.data.ts
+export default {
+  async load() {
+    const response = await fetch('https://api.example.com/data')
+    return response.json()
+  }
+}
+```
+
+## Local Files with Watch
+
+Process local files with hot reload:
+
+```ts
+// posts.data.ts
+import fs from 'node:fs'
+import { parse } from 'csv-parse/sync'
+
+export default {
+  watch: ['./data/*.csv'],
+  load(watchedFiles) {
+    // watchedFiles = array of absolute paths
+    return watchedFiles.map(file => {
+      return parse(fs.readFileSync(file, 'utf-8'), {
+        columns: true,
+        skip_empty_lines: true
+      })
+    })
+  }
+}
+```
+
+## createContentLoader
+
+Helper for loading markdown content (common for blogs/archives):
+
+```ts
+// posts.data.ts
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md')
+```
+
+Returns array of `ContentData`:
+
+```ts
+interface ContentData {
+  url: string                    // e.g. /posts/hello.html
+  frontmatter: Record<string, any>
+  src?: string                   // raw markdown (opt-in)
+  html?: string                  // rendered HTML (opt-in)
+  excerpt?: string               // excerpt HTML (opt-in)
+}
+```
+
+With options:
+
+```ts
+// posts.data.ts
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', {
+  includeSrc: true,     // Include raw markdown
+  render: true,         // Include rendered HTML
+  excerpt: true,        // Include excerpt (content before first ---)
+  
+  transform(rawData) {
+    // Sort by date, newest first
+    return rawData
+      .sort((a, b) => +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date))
+      .map(page => ({
+        title: page.frontmatter.title,
+        url: page.url,
+        date: page.frontmatter.date,
+        excerpt: page.excerpt
+      }))
+  }
+})
+```
+
+## Usage Example: Blog Index
+
+```ts
+// posts.data.ts
+import { createContentLoader } from 'vitepress'
+
+export default createContentLoader('posts/*.md', {
+  excerpt: true,
+  transform(data) {
+    return data
+      .filter(post => !post.frontmatter.draft)
+      .sort((a, b) => +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date))
+  }
+})
+```
+
+```vue
+<!-- posts/index.md -->
+<script setup>
+import { data as posts } from './posts.data.ts'
+</script>
+
+<template>
+  <ul>
+    <li v-for="post in posts" :key="post.url">
+      <a :href="post.url">{{ post.frontmatter.title }}</a>
+      <span>{{ post.frontmatter.date }}</span>
+    </li>
+  </ul>
+</template>
+```
+
+## Typed Data Loaders
+
+```ts
+// example.data.ts
+import { defineLoader } from 'vitepress'
+
+export interface Data {
+  posts: Array<{ title: string; url: string }>
+}
+
+declare const data: Data
+export { data }
+
+export default defineLoader({
+  watch: ['./posts/*.md'],
+  async load(): Promise<Data> {
+    // ...
+    return { posts: [] }
+  }
+})
+```
+
+## In Build Hooks
+
+Use in config for generating additional files:
+
+```ts
+// .vitepress/config.ts
+import { createContentLoader } from 'vitepress'
+
+export default {
+  async buildEnd() {
+    const posts = await createContentLoader('posts/*.md').load()
+    // Generate RSS feed, sitemap, etc.
+  }
+}
+```
+
+## Accessing Config
+
+```ts
+// example.data.ts
+import type { SiteConfig } from 'vitepress'
+
+export default {
+  load() {
+    const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
+    return { base: config.site.base }
+  }
+}
+```
+
+## Key Points
+
+- Data loaders run only at build time in Node.js
+- File must end with `.data.js` or `.data.ts`
+- Import the `data` named export (not default)
+- Use `watch` for local file hot reload during dev
+- `createContentLoader` simplifies loading markdown collections
+- Keep data small - it's inlined in the client bundle
+- Heavy data should use `transform` to reduce payload
+
+<!--
+Source references:
+- https://vitepress.dev/guide/data-loading
+-->

package/skills/vitepress/references/features-dynamic-routes.md

@@ -0,0 +1,235 @@
+---
+name: vitepress-dynamic-routes
+description: Generate multiple pages from a single markdown template using paths loader files
+---
+
+# Dynamic Routes
+
+Generate many pages from a single markdown file and dynamic data. Useful for blogs, package docs, or any data-driven pages.
+
+## Basic Setup
+
+Create a template file with parameter in brackets and a paths loader:
+
+```
+.
+└─ packages/
+   ├─ [pkg].md           # Route template
+   └─ [pkg].paths.js     # Paths loader
+```
+
+The paths loader exports a `paths` method returning route parameters:
+
+```js
+// packages/[pkg].paths.js
+export default {
+  paths() {
+    return [
+      { params: { pkg: 'foo' }},
+      { params: { pkg: 'bar' }},
+      { params: { pkg: 'baz' }}
+    ]
+  }
+}
+```
+
+Generated pages:
+- `/packages/foo.html`
+- `/packages/bar.html`
+- `/packages/baz.html`
+
+## Multiple Parameters
+
+```
+.
+└─ packages/
+   ├─ [pkg]-[version].md
+   └─ [pkg]-[version].paths.js
+```
+
+```js
+// packages/[pkg]-[version].paths.js
+export default {
+  paths() {
+    return [
+      { params: { pkg: 'foo', version: '1.0.0' }},
+      { params: { pkg: 'foo', version: '2.0.0' }},
+      { params: { pkg: 'bar', version: '1.0.0' }}
+    ]
+  }
+}
+```
+
+## Dynamic Path Generation
+
+From local files:
+
+```js
+// packages/[pkg].paths.js
+import fs from 'node:fs'
+
+export default {
+  paths() {
+    return fs.readdirSync('packages').map(pkg => ({
+      params: { pkg }
+    }))
+  }
+}
+```
+
+From remote API:
+
+```js
+// packages/[pkg].paths.js
+export default {
+  async paths() {
+    const packages = await fetch('https://api.example.com/packages').then(r => r.json())
+    
+    return packages.map(pkg => ({
+      params: {
+        pkg: pkg.name,
+        version: pkg.version
+      }
+    }))
+  }
+}
+```
+
+## Accessing Params in Page
+
+Template globals:
+
+```md
+<!-- packages/[pkg].md -->
+# Package: {{ $params.pkg }}
+
+Version: {{ $params.version }}
+```
+
+In script:
+
+```vue
+<script setup>
+import { useData } from 'vitepress'
+const { params } = useData()
+</script>
+
+<template>
+  <h1>{{ params.pkg }}</h1>
+</template>
+```
+
+## Passing Content
+
+For heavy content (raw markdown/HTML from CMS), use `content` instead of params to avoid bloating the client bundle:
+
+```js
+// posts/[slug].paths.js
+export default {
+  async paths() {
+    const posts = await fetch('https://cms.example.com/posts').then(r => r.json())
+    
+    return posts.map(post => ({
+      params: { slug: post.slug },
+      content: post.content  // Raw markdown or HTML
+    }))
+  }
+}
+```
+
+Render content in template:
+
+```md
+<!-- posts/[slug].md -->
+---
+title: {{ $params.title }}
+---
+
+<!-- @content -->
+```
+
+The `<!-- @content -->` placeholder is replaced with the content from the paths loader.
+
+## Watch Option
+
+Auto-rebuild when template or data files change:
+
+```js
+// posts/[slug].paths.js
+export default {
+  watch: [
+    './templates/**/*.njk',
+    '../data/**/*.json'
+  ],
+  
+  paths(watchedFiles) {
+    const dataFiles = watchedFiles.filter(f => f.endsWith('.json'))
+    
+    return dataFiles.map(file => {
+      const data = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      return {
+        params: { slug: data.slug },
+        content: renderTemplate(data)
+      }
+    })
+  }
+}
+```
+
+## Complete Example: Blog
+
+```js
+// posts/[slug].paths.js
+import fs from 'node:fs'
+import matter from 'gray-matter'
+
+export default {
+  watch: ['./posts/*.md'],
+  
+  paths(files) {
+    return files
+      .filter(f => !f.includes('[slug]'))
+      .map(file => {
+        const content = fs.readFileSync(file, 'utf-8')
+        const { data, content: body } = matter(content)
+        const slug = file.match(/([^/]+)\.md$/)[1]
+        
+        return {
+          params: { 
+            slug,
+            title: data.title,
+            date: data.date
+          },
+          content: body
+        }
+      })
+  }
+}
+```
+
+```md
+<!-- posts/[slug].md -->
+---
+layout: doc
+---
+
+# {{ $params.title }}
+
+<time>{{ $params.date }}</time>
+
+<!-- @content -->
+```
+
+## Key Points
+
+- Template file uses `[param]` syntax in filename
+- Paths loader file must be named `[param].paths.js` or `.ts`
+- `paths()` returns array of `{ params: {...}, content?: string }`
+- Use `$params` in templates or `useData().params` in scripts
+- Use `content` for heavy data to avoid client bundle bloat
+- `watch` enables HMR for template/data file changes
+
+<!--
+Source references:
+- https://vitepress.dev/guide/routing#dynamic-routes
+-->

package/skills/vitepress/references/features-vue.md

@@ -0,0 +1,224 @@
+---
+name: vue-in-vitepress-markdown
+description: Using Vue components, script setup, directives, and templating in markdown files
+---
+
+# Vue in Markdown
+
+VitePress markdown files are compiled as Vue Single-File Components, enabling full Vue functionality.
+
+## Interpolation
+
+Vue expressions work in markdown:
+
+```md
+{{ 1 + 1 }}
+
+{{ new Date().toLocaleDateString() }}
+```
+
+## Directives
+
+HTML with Vue directives:
+
+```md
+<span v-for="i in 3">{{ i }}</span>
+
+<div v-if="$frontmatter.showBanner">
+  Banner content
+</div>
+```
+
+## Script and Style
+
+Add `<script setup>` and `<style>` after frontmatter:
+
+```md
+---
+title: My Page
+---
+
+<script setup>
+import { ref } from 'vue'
+import MyComponent from './MyComponent.vue'
+
+const count = ref(0)
+</script>
+
+# {{ $frontmatter.title }}
+
+Count: {{ count }}
+
+<button @click="count++">Increment</button>
+
+<MyComponent />
+
+<style module>
+.button {
+  color: red;
+}
+</style>
+```
+
+**Note:** Use `<style module>` instead of `<style scoped>` to avoid bloating page size.
+
+## Importing Components
+
+Local import (code-split per page):
+
+```md
+<script setup>
+import CustomComponent from '../components/CustomComponent.vue'
+</script>
+
+<CustomComponent />
+```
+
+## Global Components
+
+Register in theme for use everywhere:
+
+```ts
+// .vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+import MyGlobalComponent from './MyGlobalComponent.vue'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('MyGlobalComponent', MyGlobalComponent)
+  }
+}
+```
+
+Then use in any markdown:
+
+```md
+<MyGlobalComponent />
+```
+
+**Important:** Component names must contain a hyphen or be PascalCase to avoid being treated as inline HTML elements.
+
+## Runtime API
+
+Access VitePress data:
+
+```md
+<script setup>
+import { useData, useRoute, useRouter } from 'vitepress'
+
+const { page, frontmatter, theme, site } = useData()
+const route = useRoute()
+const router = useRouter()
+</script>
+
+Current page: {{ page.relativePath }}
+```
+
+## Global Variables
+
+Available without import:
+
+```md
+# {{ $frontmatter.title }}
+
+Params: {{ $params.id }}
+```
+
+## Components in Headers
+
+```md
+# My Title <Badge type="tip" text="v2.0" />
+```
+
+## Escaping Vue Syntax
+
+Prevent Vue interpolation:
+
+```md
+<span v-pre>{{ will be displayed as-is }}</span>
+```
+
+Or use container:
+
+```md
+::: v-pre
+{{ this won't be processed }}
+:::
+```
+
+## Vue in Code Blocks
+
+Enable Vue processing in fenced code with `-vue` suffix:
+
+````md
+```js-vue
+Hello {{ 1 + 1 }}
+```
+````
+
+## CSS Pre-processors
+
+Supported out of the box (install the preprocessor):
+
+```bash
+npm install -D sass  # for .scss/.sass
+npm install -D less  # for .less
+npm install -D stylus # for .styl/.stylus
+```
+
+```vue
+<style lang="scss">
+.title {
+  font-size: 20px;
+}
+</style>
+```
+
+## Using Teleports
+
+Teleport to body only with SSG:
+
+```md
+<ClientOnly>
+  <Teleport to="#modal">
+    <div>Modal content</div>
+  </Teleport>
+</ClientOnly>
+```
+
+## VS Code IntelliSense
+
+Enable Vue language features for `.md` files:
+
+```json
+// tsconfig.json
+{
+  "include": ["docs/**/*.ts", "docs/**/*.vue", "docs/**/*.md"],
+  "vueCompilerOptions": {
+    "vitePressExtensions": [".md"]
+  }
+}
+```
+
+```json
+// .vscode/settings.json
+{
+  "vue.server.includeLanguages": ["vue", "markdown"]
+}
+```
+
+## Key Points
+
+- Markdown files are Vue SFCs - use `<script setup>` and `<style>`
+- Access page data via `useData()` or `$frontmatter` global
+- Import components locally or register globally in theme
+- Use `<style module>` instead of `<style scoped>`
+- Wrap non-SSR components in `<ClientOnly>`
+- Component names must be PascalCase or contain hyphens
+
+<!--
+Source references:
+- https://vitepress.dev/guide/using-vue
+- https://vitepress.dev/reference/runtime-api
+-->