moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-library-nextra/modules/mdx-components.md

@@ -0,0 +1,52 @@
+# MDX Components
+
+## Overview
+
+Reusable MDX components for enhanced documentation.
+
+## Core Components
+
+### Callout Component
+
+```mdx
+<Callout type="info">
+ Important information here
+</Callout>
+
+<Callout type="warning">
+ Warning message
+</Callout>
+```
+
+### Code Block Component
+
+```mdx
+<CodeBlock language="python" highlight="2,4-6">
+{`
+def example():
+ # Highlighted line
+ result = process()
+ # More highlighted lines
+ return result
+`}
+</CodeBlock>
+```
+
+## Custom Components
+
+### Tabs Component
+
+```mdx
+<Tabs>
+ <Tab label="Python">
+ Python code example
+ </Tab>
+ <Tab label="JavaScript">
+ JavaScript code example
+ </Tab>
+</Tabs>
+```
+
+---
+Last Updated: 2025-11-23
+Status: Production Ready

moai_adk/templates/.claude/skills/moai-library-nextra/optimization.md

@@ -0,0 +1,303 @@
+---
+name: moai-library-nextra/optimization
+description: Performance optimization for Nextra sites, caching, static generation, and deployment
+---
+
+# Nextra Architecture Optimization (v5.0.0)
+
+## Static Generation and Caching
+
+### 1. Incremental Static Regeneration (ISR)
+
+```typescript
+// pages/docs/[...slug].tsx
+import { GetStaticProps, GetStaticPaths } from 'next';
+
+interface DocsPageProps {
+ content: string;
+ meta: PageMetadata;
+}
+
+export const getStaticPaths: GetStaticPaths = async () => {
+ // Generate paths for all documentation pages
+ const pages = await getAllDocumentationPages();
+
+ return {
+ paths: pages.map(page => ({
+ params: { slug: page.path.split('/').filter(Boolean) }
+ })),
+ fallback: 'blocking' // Generate on-demand
+ };
+};
+
+export const getStaticProps: GetStaticProps<DocsPageProps> = async ({ params }) => {
+ const slug = Array.isArray(params?.slug) ? params.slug.join('/') : params?.slug;
+
+ try {
+ const { content, meta } = await getDocumentationPage(slug);
+
+ return {
+ props: { content, meta },
+ revalidate: 3600 // ISR: revalidate every hour
+ };
+ } catch (error) {
+ return {
+ notFound: true,
+ revalidate: 60 // Retry failed pages more frequently
+ };
+ }
+};
+
+export default function DocsPage({ content, meta }: DocsPageProps) {
+ return (
+ <article>
+ <h1>{meta.title}</h1>
+ <div dangerouslySetInnerHTML={{ __html: content }} />
+ </article>
+ );
+}
+```
+
+### 2. Build-Time Optimization
+
+```typescript
+// next.config.js
+module.exports = {
+ // Optimize images
+ images: {
+ formats: ['image/avif', 'image/webp'],
+ unoptimized: false
+ },
+
+ // Compression
+ compress: true,
+ poweredByHeader: false,
+
+ // SWC minification (faster than Terser)
+ swcMinify: true,
+
+ // React optimization
+ reactStrictMode: true,
+
+ // Font optimization
+ optimizeFonts: true,
+
+ // Experimental features for better performance
+ experimental: {
+ optimizePackageImports: [
+ '@mui/material',
+ '@mui/icons-material'
+ ]
+ },
+
+ // Custom webpack config
+ webpack: (config, { isServer }) => {
+ // Tree shaking optimization
+ config.optimization.usedExports = true;
+
+ return config;
+ }
+};
+```
+
+## Content Caching Strategy
+
+### 1. Multi-Layer Caching
+
+```typescript
+class DocumentationCache {
+ private fileCache = new Map<string, CacheEntry>();
+ private renderCache = new Map<string, CacheEntry>();
+
+ async getDocumentationPage(slug: string): Promise<PageContent> {
+ // Layer 1: In-memory render cache (milliseconds)
+ const renderCached = this.renderCache.get(slug);
+ if (renderCached && !this.isExpired(renderCached)) {
+ return renderCached.data;
+ }
+
+ // Layer 2: File system cache (seconds)
+ const fileCached = this.fileCache.get(slug);
+ if (fileCached && !this.isExpired(fileCached)) {
+ return fileCached.data;
+ }
+
+ // Layer 3: Read from disk
+ const content = await this.readFromDisk(slug);
+
+ // Cache to all layers
+ this.fileCache.set(slug, {
+ data: content,
+ timestamp: Date.now(),
+ ttl: 3600000 // 1 hour
+ });
+
+ this.renderCache.set(slug, {
+ data: content,
+ timestamp: Date.now(),
+ ttl: 60000 // 1 minute
+ });
+
+ return content;
+ }
+
+ private isExpired(entry: CacheEntry): boolean {
+ return Date.now() - entry.timestamp > entry.ttl;
+ }
+}
+```
+
+## Search Performance Optimization
+
+### 1. Index Compression and Caching
+
+```typescript
+class OptimizedSearchIndex {
+ async buildCompressedIndex(documents: SearchableContent[]): Promise<Buffer> {
+ // Create optimized index structure
+ const index = {
+ documents: documents.map(doc => ({
+ id: doc.id,
+ title: doc.title,
+ tokens: this.tokenize(doc.content)
+ })),
+ invertedIndex: this.buildInvertedIndex(documents),
+ metadata: {
+ version: 1,
+ generated: Date.now(),
+ count: documents.length
+ }
+ };
+
+ // Compress with brotli (better compression than gzip)
+ const json = JSON.stringify(index);
+ const compressed = await this.brotliCompress(json);
+
+ // Cache compressed index
+ await this.cacheIndex(compressed);
+
+ return compressed;
+ }
+
+ private buildInvertedIndex(
+ documents: SearchableContent[]
+ ): Map<string, number[]> {
+ const invertedIndex = new Map<string, number[]>();
+
+ documents.forEach((doc, idx) => {
+ const tokens = this.tokenize(doc.content);
+
+ for (const token of tokens) {
+ if (!invertedIndex.has(token)) {
+ invertedIndex.set(token, []);
+ }
+
+ invertedIndex.get(token)!.push(idx);
+ }
+ });
+
+ return invertedIndex;
+ }
+
+ private tokenize(text: string): string[] {
+ return text
+ .toLowerCase()
+ .match(/\b\w+\b/g) || [];
+ }
+
+ private async brotliCompress(data: string): Promise<Buffer> {
+ return new Promise((resolve, reject) => {
+ require('brotli').compress(Buffer.from(data), (err: any, output: Buffer) => {
+ if (err) reject(err);
+ else resolve(output);
+ });
+ });
+ }
+}
+```
+
+## Deployment Optimization
+
+### 1. Vercel Deployment Configuration
+
+```typescript
+// vercel.json
+{
+ "buildCommand": "next build",
+ "outputDirectory": ".next",
+ "devCommand": "next dev",
+ "env": {
+ "SEARCH_ENABLED": "@search_enabled"
+ },
+ "functions": {
+ "pages/api/": {
+ "memory": 256,
+ "maxDuration": 30
+ }
+ },
+ "redirects": [
+ {
+ "source": "/docs/:slug*",
+ "destination": "/:slug*"
+ }
+ ],
+ "headers": [
+ {
+ "source": "/(_next|public)/:path*",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "public, max-age=31536000, immutable"
+ }
+ ]
+ },
+ {
+ "source": "/:path*",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "public, max-age=3600, s-maxage=86400"
+ }
+ ]
+ }
+ ]
+}
+```
+
+### 2. Performance Monitoring
+
+```typescript
+class NextraPerformanceMonitor {
+ async trackPageLoad(slug: string, duration: number) {
+ metrics.observe('page.load.duration', duration, {
+ page: slug,
+ bucket: this.getDurationBucket(duration)
+ });
+
+ // Alert if exceeds budget
+ if (duration > 3000) {
+ metrics.increment('page.load.slow');
+ logger.warn('Slow page load', { slug, duration });
+ }
+ }
+
+ async trackBuildTime(buildDuration: number) {
+ metrics.observe('build.duration', buildDuration);
+
+ if (buildDuration > 600000) { // 10 minutes
+ metrics.increment('build.slow');
+ logger.warn('Slow build detected', { buildDuration });
+ }
+ }
+
+ private getDurationBucket(duration: number): string {
+ if (duration < 1000) return 'fast';
+ if (duration < 3000) return 'normal';
+ return 'slow';
+ }
+}
+```
+
+---
+
+Version: 5.0.0 | Last Updated: 2025-11-22 | Enterprise Ready:

moai_adk/templates/.claude/skills/moai-library-nextra/reference.md

@@ -0,0 +1,379 @@
+# moai-library-nextra Reference
+
+## API Reference
+
+### Theme Configuration API
+
+DocsThemeConfig Interface:
+- `logo`: React node for site logo
+- `logoLink`: URL for logo click
+- `project`: Project link configuration
+- `docsRepositoryBase`: Base URL for edit links
+- `sidebar`: Sidebar configuration options
+- `toc`: Table of contents options
+- `footer`: Footer configuration
+- `head`: Custom head elements
+- `search`: Search configuration
+- `useNextSeoProps`: SEO metadata function
+
+Sidebar Options:
+- `defaultMenuCollapseLevel`: Default collapse depth
+- `toggleButton`: Show toggle button
+- `autoCollapse`: Auto-collapse inactive sections
+
+TOC Options:
+- `backToTop`: Show back to top button
+- `float`: Float table of contents
+- `headingDepth`: Heading levels to include
+
+### Navigation API (\_meta.js)
+
+Page Configuration:
+```javascript
+{
+  "page-name": "Display Title",
+  "---": "",  // Separator
+  "external-link": {
+    "title": "Link Title",
+    "href": "https://example.com",
+    "newWindow": true
+  }
+}
+```
+
+Page Options:
+- `title`: Display title in sidebar
+- `type`: Page type (page, separator, menu)
+- `display`: Display mode (normal, hidden, children)
+- `theme`: Page-specific theme overrides
+
+### MDX Component API
+
+Built-in Components:
+- `Callout`: Alert/info boxes (type: info, warning, error, default)
+- `Tabs`: Tabbed content container
+- `Tab`: Individual tab item
+- `Cards`: Card grid container
+- `Card`: Individual card item
+- `Steps`: Step-by-step guide
+- `FileTree`: File structure visualization
+
+Callout Types:
+- `info`: Blue informational box
+- `warning`: Yellow warning box
+- `error`: Red error/danger box
+- `default`: Gray neutral box
+
+### Search API
+
+FlexSearch Configuration:
+- `placeholder`: Search input placeholder
+- `emptyResult`: Empty result message
+- `loading`: Loading indicator
+- `error`: Error message
+
+Search Customization:
+- Custom search endpoint
+- Result filtering
+- Keyboard shortcuts
+
+---
+
+## Configuration Options
+
+### next.config.js
+
+Nextra Plugin Configuration:
+```javascript
+const withNextra = require("nextra")({
+  theme: "nextra-theme-docs",
+  themeConfig: "./theme.config.tsx",
+  staticImage: true,
+  latex: true,
+  flexsearch: {
+    codeblocks: true
+  },
+  defaultShowCopyCode: true
+});
+
+module.exports = withNextra({
+  // Next.js config
+  reactStrictMode: true,
+  images: {
+    domains: ["example.com"]
+  }
+});
+```
+
+### theme.config.tsx
+
+Full Configuration Example:
+```typescript
+const config: DocsThemeConfig = {
+  // Branding
+  logo: <span>My Documentation</span>,
+  logoLink: "/",
+
+  // Repository
+  project: { link: "https://github.com/user/repo" },
+  docsRepositoryBase: "https://github.com/user/repo/tree/main",
+
+  // Navigation
+  sidebar: {
+    defaultMenuCollapseLevel: 1,
+    toggleButton: true,
+    autoCollapse: true
+  },
+
+  // Content
+  toc: {
+    backToTop: true,
+    float: true
+  },
+
+  // Footer
+  footer: {
+    text: `${new Date().getFullYear()} My Project`
+  },
+
+  // SEO
+  head: (
+    <>
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <meta property="og:title" content="My Docs" />
+      <meta property="og:description" content="Documentation" />
+    </>
+  ),
+
+  useNextSeoProps() {
+    return {
+      titleTemplate: "%s - My Docs"
+    };
+  }
+};
+```
+
+### Internationalization (i18n)
+
+next.config.js i18n:
+```javascript
+module.exports = withNextra({
+  i18n: {
+    locales: ["en", "ko", "ja"],
+    defaultLocale: "en"
+  }
+});
+```
+
+Language-specific \_meta:
+```
+pages/
+  en/
+    _meta.json
+    index.mdx
+  ko/
+    _meta.json
+    index.mdx
+```
+
+---
+
+## Integration Patterns
+
+### Project Structure Pattern
+
+Recommended Directory Layout:
+```
+docs/
+  pages/
+    _app.tsx
+    _meta.json
+    index.mdx
+    getting-started/
+      _meta.json
+      installation.mdx
+      configuration.mdx
+    guides/
+      _meta.json
+      basic.mdx
+      advanced.mdx
+    api/
+      _meta.json
+      reference.mdx
+  public/
+    images/
+    og-image.png
+  components/
+    CustomComponent.tsx
+  styles/
+    custom.css
+  theme.config.tsx
+  next.config.js
+  package.json
+```
+
+### Custom Component Integration
+
+Creating Custom Components:
+1. Create component in `components/` directory
+2. Import in MDX files
+3. Use standard React patterns
+
+Global Component Registration:
+```typescript
+// pages/_app.tsx
+import type { AppProps } from "next/app";
+import { CustomComponent } from "../components/CustomComponent";
+
+const components = {
+  CustomComponent
+};
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} components={components} />;
+}
+```
+
+### Static Export Pattern
+
+Static HTML Generation:
+```javascript
+// next.config.js
+module.exports = withNextra({
+  output: "export",
+  images: {
+    unoptimized: true
+  },
+  trailingSlash: true
+});
+```
+
+Build Command:
+```bash
+npm run build
+# Output in /out directory
+```
+
+### Theme Customization Pattern
+
+CSS Variables Override:
+```css
+/* styles/custom.css */
+:root {
+  --nextra-primary-hue: 212deg;
+  --nextra-primary-saturation: 100%;
+  --nextra-content-width: 90rem;
+}
+
+.dark {
+  --nextra-bg: 17 17 17;
+}
+```
+
+Tailwind Integration:
+```javascript
+// tailwind.config.js
+module.exports = {
+  content: [
+    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx}",
+    "./theme.config.tsx"
+  ]
+};
+```
+
+---
+
+## Troubleshooting
+
+### Build Errors
+
+Symptoms: Build fails, module not found
+
+Solutions:
+1. Clear `.next` cache: `rm -rf .next`
+2. Reinstall dependencies: `rm -rf node_modules && npm install`
+3. Check Next.js/Nextra version compatibility
+4. Verify theme.config.tsx syntax
+
+### MDX Parsing Errors
+
+Symptoms: MDX syntax errors, component not rendering
+
+Solutions:
+1. Check JSX syntax in MDX files
+2. Verify component imports are correct
+3. Ensure no unescaped special characters
+4. Check for unclosed tags
+
+### Search Not Working
+
+Symptoms: Search returns no results, index empty
+
+Solutions:
+1. Verify FlexSearch is enabled in next.config.js
+2. Rebuild the search index: `npm run build`
+3. Check for build errors in search indexing
+4. Verify content files are in pages directory
+
+### i18n Issues
+
+Symptoms: Wrong language, missing translations
+
+Solutions:
+1. Verify locale configuration in next.config.js
+2. Check \_meta.json exists for each locale
+3. Confirm URL structure matches locale pattern
+4. Verify default locale setting
+
+### Styling Issues
+
+Symptoms: Incorrect styles, theme not applying
+
+Solutions:
+1. Check CSS import order
+2. Verify Tailwind configuration
+3. Clear browser cache
+4. Check for CSS specificity conflicts
+
+---
+
+## External Resources
+
+### Official Documentation
+
+- [Nextra Documentation](https://nextra.site/)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [MDX Documentation](https://mdxjs.com/)
+- [FlexSearch](https://github.com/nextapps-de/flexsearch)
+
+### Deployment Guides
+
+- [Vercel Deployment](https://vercel.com/docs)
+- [GitHub Pages with Next.js](https://nextjs.org/docs/pages/building-your-application/deploying/static-exports)
+- [Netlify Deployment](https://docs.netlify.com/)
+
+### Theme Resources
+
+- Nextra Theme Docs (documentation sites)
+- Nextra Theme Blog (blog sites)
+- Custom theme development guide
+
+### Related Skills
+
+- `moai-docs-generation`: Automated documentation generation
+- `moai-workflow-docs`: Documentation workflow management
+- `moai-domain-frontend`: Frontend development patterns
+- `moai-library-mermaid`: Diagram integration
+
+### Complementary Tools
+
+- Mermaid.js: Diagram generation
+- KaTeX: Math rendering
+- Shiki: Code syntax highlighting
+- next-sitemap: SEO sitemap generation
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-06