@litodocs/cli 0.5.2 → 0.7.0

package/src/core/output.js

@@ -2,12 +2,18 @@ import pkg from 'fs-extra';
 const { copy, ensureDir } = pkg;
 import { join } from 'path';
 
-export async function copyOutput(projectDir, outputPath) {
-  const distPath = join(projectDir, 'dist');
-  
+/**
+ * Copy built output to the specified output path
+ * @param {string} projectDir - The scaffolded project directory
+ * @param {string} outputPath - User's desired output path
+ * @param {string} buildOutputDir - Framework's build output directory (default: 'dist')
+ */
+export async function copyOutput(projectDir, outputPath, buildOutputDir = 'dist') {
+  const distPath = join(projectDir, buildOutputDir);
+
   // Ensure output directory exists
   await ensureDir(outputPath);
-  
+
   // Copy built files to output
   await copy(distPath, outputPath, {
     overwrite: true,

package/src/core/sync.js

@@ -1,7 +1,8 @@
 import pkg from 'fs-extra';
 const { copy, ensureDir, remove, readFile, writeFile, pathExists } = pkg;
 import { join, relative, sep } from 'path';
-import { readdir, stat } from 'fs/promises';
+import { readdir, stat, utimes } from 'fs/promises';
+import { syncLanding } from './landing-sync.js';
 
 // Known locale codes (ISO 639-1)
 const KNOWN_LOCALES = [
@@ -12,7 +13,7 @@ const KNOWN_LOCALES = [
 ];
 
 // Special folders that are not content
-const SPECIAL_FOLDERS = ['_assets', '_css', '_images', '_static', 'public'];
+const SPECIAL_FOLDERS = ['_assets', '_css', '_images', '_static', '_landing', 'public'];
 
 /**
  * Get i18n configuration from docs-config.json
@@ -30,6 +31,21 @@ async function getI18nConfig(sourcePath) {
   return { defaultLocale: 'en', locales: ['en'] };
 }
 
+/**
+ * Get full docs-config.json
+ */
+async function getDocsConfig(sourcePath) {
+  const configPath = join(sourcePath, 'docs-config.json');
+  if (await pathExists(configPath)) {
+    try {
+      return JSON.parse(await readFile(configPath, 'utf-8'));
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
 /**
  * Get versioning configuration from docs-config.json
  */
@@ -97,8 +113,17 @@ async function detectVersionFolders(sourcePath, versioningConfig) {
   return versionFolders;
 }
 
-export async function syncDocs(sourcePath, projectDir) {
-  const targetPath = join(projectDir, 'src', 'pages');
+/**
+ * Sync documentation files to the project
+ * @param {string} sourcePath - User's docs directory
+ * @param {string} projectDir - Scaffolded project directory
+ * @param {object} frameworkConfig - Framework configuration (optional, defaults to Astro)
+ */
+export async function syncDocs(sourcePath, projectDir, frameworkConfig = null) {
+  // Default to Astro's src/pages for backward compatibility
+  const contentDir = frameworkConfig?.contentDir || 'src/pages';
+  const targetPath = join(projectDir, contentDir);
+  const shouldInjectLayout = frameworkConfig?.layoutInjection !== false;
 
   // Clear existing pages (except index if it exists in template)
   await ensureDir(targetPath);
@@ -159,8 +184,10 @@ export async function syncDocs(sourcePath, projectDir) {
       },
     });
 
-    // Inject layout into version markdown files
-    await injectLayoutIntoMarkdown(versionTargetPath, targetPath, null, [], version);
+    // Inject layout into version markdown files (only for frameworks that need it)
+    if (shouldInjectLayout) {
+      await injectLayoutIntoMarkdown(versionTargetPath, targetPath, null, [], version, frameworkConfig);
+    }
   }));
 
   // Sync locale folders
@@ -177,12 +204,16 @@ export async function syncDocs(sourcePath, projectDir) {
       },
     });
 
-    // Inject layout into locale markdown files
-    await injectLayoutIntoMarkdown(localeTargetPath, targetPath, locale);
+    // Inject layout into locale markdown files (only for frameworks that need it)
+    if (shouldInjectLayout) {
+      await injectLayoutIntoMarkdown(localeTargetPath, targetPath, locale, [], null, frameworkConfig);
+    }
   }));
 
-  // Inject layout into default locale markdown files
-  await injectLayoutIntoMarkdown(targetPath, targetPath, null, excludeFolders);
+  // Inject layout into default locale markdown files (only for frameworks that need it)
+  if (shouldInjectLayout) {
+    await injectLayoutIntoMarkdown(targetPath, targetPath, null, excludeFolders, null, frameworkConfig);
+  }
 
   // Check for custom landing page conflict
   const hasUserIndex = ['index.md', 'index.mdx'].some(file =>
@@ -198,6 +229,18 @@ export async function syncDocs(sourcePath, projectDir) {
 
   // Sync user assets (images, css, static files)
   await syncUserAssets(sourcePath, projectDir);
+
+  // Sync landing page (custom HTML/CSS/JS or sections)
+  const docsConfig = await getDocsConfig(sourcePath);
+  if (docsConfig.landing) {
+    await syncLanding(sourcePath, projectDir, frameworkConfig, docsConfig);
+  }
+
+  // Trigger HMR for non-Astro frameworks (Vite-based)
+  // Vite doesn't automatically watch content directories, so we need to trigger a reload
+  if (frameworkConfig && frameworkConfig.name !== 'astro') {
+    await triggerHMR(projectDir, frameworkConfig);
+  }
 }
 
 /**
@@ -283,7 +326,27 @@ async function syncUserAssets(sourcePath, projectDir) {
       const customImport = '@import "./custom.css";';
 
       if (!globalCss.includes(customImport)) {
-        globalCss = globalCss.trimEnd() + '\n\n/* User custom styles */\n' + customImport + '\n';
+        // @import must come at the very top of the file (before @tailwind directives)
+        // Only @charset can precede @import
+        const lines = globalCss.split('\n');
+        let insertIndex = 0;
+
+        // Find position after @charset if it exists (only thing allowed before @import)
+        for (let i = 0; i < lines.length; i++) {
+          const trimmed = lines[i].trim();
+          if (trimmed.startsWith('@charset')) {
+            insertIndex = i + 1;
+            break;
+          }
+          // Stop at first non-empty, non-comment line
+          if (trimmed && !trimmed.startsWith('/*') && !trimmed.startsWith('*') && !trimmed.startsWith('//')) {
+            break;
+          }
+        }
+
+        // Insert the import at the top (after @charset if present)
+        lines.splice(insertIndex, 0, '/* User custom styles */', customImport, '');
+        globalCss = lines.join('\n');
         await writeFile(globalCssPath, globalCss, 'utf-8');
       }
     }
@@ -299,10 +362,15 @@ async function syncUserAssets(sourcePath, projectDir) {
  * @param {string|null} locale - Current locale (null for default)
  * @param {string[]} skipFolders - Folders to skip (locale folders when processing root)
  * @param {string|null} version - Current version (null for non-versioned)
+ * @param {object|null} frameworkConfig - Framework configuration for layout paths
  */
-async function injectLayoutIntoMarkdown(dir, rootDir, locale = null, skipFolders = [], version = null) {
+async function injectLayoutIntoMarkdown(dir, rootDir, locale = null, skipFolders = [], version = null, frameworkConfig = null) {
   const entries = await readdir(dir, { withFileTypes: true });
 
+  // Get layout paths from framework config or use defaults
+  const baseLayoutPath = frameworkConfig?.layoutPath || 'layouts/MarkdownLayout.astro';
+  const apiLayoutPath = frameworkConfig?.apiLayoutPath || 'layouts/APILayout.astro';
+
   await Promise.all(entries.map(async (entry) => {
     const fullPath = join(dir, entry.name);
 
@@ -311,14 +379,14 @@ async function injectLayoutIntoMarkdown(dir, rootDir, locale = null, skipFolders
       if (skipFolders.includes(entry.name)) {
         return;
       }
-      await injectLayoutIntoMarkdown(fullPath, rootDir, locale, [], version);
+      await injectLayoutIntoMarkdown(fullPath, rootDir, locale, [], version, frameworkConfig);
     } else if (entry.name.endsWith('.md') || entry.name.endsWith('.mdx')) {
       let content = await readFile(fullPath, 'utf-8');
 
       // Calculate relative path to layout
       const relPath = relative(rootDir, fullPath);
       const depth = relPath.split(sep).length - 1;
-      const layoutPath = '../'.repeat(depth + 1) + 'layouts/MarkdownLayout.astro';
+      const layoutPath = '../'.repeat(depth + 1) + baseLayoutPath;
 
       // Check if file already has frontmatter
       if (content.startsWith('---')) {
@@ -330,7 +398,7 @@ async function injectLayoutIntoMarkdown(dir, rootDir, locale = null, skipFolders
           // Determine which layout to use
           let targetLayout = layoutPath;
           if (frontmatterBlock.includes('api:')) {
-            targetLayout = '../'.repeat(depth + 1) + 'layouts/APILayout.astro';
+            targetLayout = '../'.repeat(depth + 1) + apiLayoutPath;
           }
 
           // Add locale to frontmatter if present
@@ -362,3 +430,61 @@ async function injectLayoutIntoMarkdown(dir, rootDir, locale = null, skipFolders
     }
   }));
 }
+
+/**
+ * Trigger HMR for Vite-based frameworks
+ * Vite watches certain files for changes - we touch a trigger file to force a reload
+ * @param {string} projectDir - Project directory
+ * @param {object} frameworkConfig - Framework configuration
+ */
+async function triggerHMR(projectDir, frameworkConfig) {
+  // Use framework-specific HMR trigger file if defined
+  const triggerFilePath = frameworkConfig.hmrTriggerFile
+    ? join(projectDir, frameworkConfig.hmrTriggerFile)
+    : join(projectDir, 'src', '.lito-hmr-trigger.js');
+
+  try {
+    // Ensure parent directory exists
+    await ensureDir(join(projectDir, 'src'));
+
+    // Write a timestamp to the trigger file
+    // This file should be imported in the app's entry point
+    const timestamp = Date.now();
+    const content = `// Auto-generated by Lito CLI for HMR triggering
+// This file is updated when docs content changes
+// Import this file in your app's entry point to enable content hot reload
+export const LITO_CONTENT_VERSION = ${timestamp};
+export const LITO_LAST_UPDATE = "${new Date().toISOString()}";
+
+// Force Vite to treat this as a module that triggers HMR
+if (import.meta.hot) {
+  import.meta.hot.accept();
+}
+`;
+
+    await writeFile(triggerFilePath, content, 'utf-8');
+  } catch {
+    // Fallback: Touch the main entry file or vite config
+    const fallbackFiles = [
+      join(projectDir, 'src', 'main.jsx'),
+      join(projectDir, 'src', 'main.tsx'),
+      join(projectDir, 'src', 'App.jsx'),
+      join(projectDir, 'src', 'App.tsx'),
+      join(projectDir, 'src', 'index.jsx'),
+      join(projectDir, 'src', 'index.tsx'),
+    ];
+
+    for (const file of fallbackFiles) {
+      if (await pathExists(file)) {
+        try {
+          // Touch the file by updating its mtime
+          const now = new Date();
+          await utimes(file, now, now);
+          break;
+        } catch {
+          // Continue to next file
+        }
+      }
+    }
+  }
+}

package/src/core/template-registry.js

@@ -9,12 +9,15 @@
  */
 
 export const TEMPLATE_REGISTRY = {
-    // Default template (fetched from GitHub)
-    'default': 'github:Lito-docs/template',
+    // Default template - Astro-based
+    'default': 'github:Lito-docs/lito-astro-template',
 
-    // Official templates
-    // 'modern': 'github:devrohit06/lito-theme-modern',
-    // 'minimal': 'github:devrohit06/lito-theme-minimal',
+    // Framework-specific templates
+    'astro': 'github:Lito-docs/lito-astro-template',
+    'react': 'github:Lito-docs/lito-react-template',
+    'next': 'github:Lito-docs/lito-next-template',
+    'vue': 'github:Lito-docs/lito-vue-template',
+    'nuxt': 'github:Lito-docs/lito-nuxt-template',
 };
 
 /**

package/src/schema/core-schema.json

@@ -0,0 +1,262 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lito.dev/schemas/core-config.json",
+  "title": "Lito Core Configuration Schema",
+  "description": "This schema defines the REQUIRED configuration that ALL Lito templates must support. Users can swap templates without changing any of these options.",
+  "type": "object",
+  "required": ["metadata"],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "description": "Site metadata - REQUIRED by all templates",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of your documentation site"
+        },
+        "description": {
+          "type": "string",
+          "description": "A brief description of your documentation"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The production URL of your documentation site"
+        },
+        "version": {
+          "type": "string",
+          "description": "The version of your documentation"
+        }
+      },
+      "required": ["name"]
+    },
+    "branding": {
+      "type": "object",
+      "description": "Core branding options - supported by all templates",
+      "properties": {
+        "logo": {
+          "type": "object",
+          "description": "Logo configuration",
+          "properties": {
+            "light": {
+              "type": "string",
+              "description": "Path to logo for light mode"
+            },
+            "dark": {
+              "type": "string",
+              "description": "Path to logo for dark mode"
+            },
+            "href": {
+              "type": "string",
+              "description": "Link when clicking the logo"
+            }
+          }
+        },
+        "favicon": {
+          "type": "string",
+          "description": "Path to favicon"
+        },
+        "colors": {
+          "type": "object",
+          "description": "Core color configuration",
+          "properties": {
+            "primary": {
+              "type": "string",
+              "description": "Primary brand color (hex, rgb, or color name)"
+            }
+          }
+        }
+      }
+    },
+    "navigation": {
+      "type": "object",
+      "description": "Navigation structure - REQUIRED by all templates",
+      "properties": {
+        "navbar": {
+          "type": "object",
+          "description": "Top navigation bar configuration",
+          "properties": {
+            "links": {
+              "type": "array",
+              "description": "Navigation links in the header",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "label": { "type": "string" },
+                  "href": { "type": "string" }
+                },
+                "required": ["label", "href"]
+              }
+            },
+            "cta": {
+              "type": "object",
+              "description": "Call-to-action button",
+              "properties": {
+                "label": { "type": "string" },
+                "href": { "type": "string" }
+              }
+            }
+          }
+        },
+        "sidebar": {
+          "type": "array",
+          "description": "Sidebar navigation groups",
+          "items": {
+            "$ref": "#/$defs/sidebarGroup"
+          }
+        }
+      }
+    },
+    "search": {
+      "type": "object",
+      "description": "Search configuration - supported by all templates",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable search functionality"
+        },
+        "provider": {
+          "type": "string",
+          "enum": ["local", "algolia"],
+          "default": "local",
+          "description": "Search provider"
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "Search docs...",
+          "description": "Search input placeholder text"
+        }
+      }
+    },
+    "seo": {
+      "type": "object",
+      "description": "SEO configuration - supported by all templates",
+      "properties": {
+        "ogImage": {
+          "type": "string",
+          "description": "Default Open Graph image URL"
+        },
+        "twitterHandle": {
+          "type": "string",
+          "description": "Twitter handle (e.g., @username)"
+        },
+        "defaultAuthor": {
+          "type": "string",
+          "description": "Default author name"
+        },
+        "defaultKeywords": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Default keywords for all pages"
+        }
+      }
+    },
+    "i18n": {
+      "type": "object",
+      "description": "Internationalization - supported by all templates",
+      "properties": {
+        "defaultLocale": {
+          "type": "string",
+          "default": "en",
+          "description": "Default locale"
+        },
+        "locales": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["en"],
+          "description": "Supported locales"
+        },
+        "routing": {
+          "type": "object",
+          "properties": {
+            "prefixDefaultLocale": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "description": "Asset folder configuration - supported by all templates",
+      "properties": {
+        "images": {
+          "type": "string",
+          "default": "_images",
+          "description": "Images folder name"
+        },
+        "css": {
+          "type": "string",
+          "default": "_css",
+          "description": "CSS folder name"
+        },
+        "static": {
+          "type": "string",
+          "default": "_assets",
+          "description": "Static assets folder name"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "sidebarGroup": {
+      "type": "object",
+      "description": "A sidebar navigation group",
+      "properties": {
+        "label": {
+          "type": "string",
+          "description": "Group heading"
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon name (Iconify format)"
+        },
+        "items": {
+          "type": "array",
+          "description": "Navigation items in this group",
+          "items": {
+            "$ref": "#/$defs/sidebarItem"
+          }
+        }
+      },
+      "required": ["label", "items"]
+    },
+    "sidebarItem": {
+      "type": "object",
+      "description": "A sidebar navigation item",
+      "properties": {
+        "label": {
+          "type": "string",
+          "description": "Link text"
+        },
+        "slug": {
+          "type": "string",
+          "description": "Page slug (relative path without extension)"
+        },
+        "href": {
+          "type": "string",
+          "description": "External URL (use instead of slug for external links)"
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon name (Iconify format)"
+        },
+        "method": {
+          "type": "string",
+          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+          "description": "HTTP method for API endpoints"
+        },
+        "items": {
+          "type": "array",
+          "description": "Nested items for sub-groups",
+          "items": {
+            "$ref": "#/$defs/sidebarItem"
+          }
+        }
+      },
+      "required": ["label"]
+    }
+  }
+}

package/src/schema/template-manifest.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lito.dev/schemas/template-manifest.json",
+  "title": "Lito Template Manifest",
+  "description": "Defines a template's capabilities and supported configuration extensions",
+  "type": "object",
+  "required": ["name", "version", "coreSchemaVersion"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Template name"
+    },
+    "version": {
+      "type": "string",
+      "description": "Template version (semver)"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of the template"
+    },
+    "author": {
+      "type": "string",
+      "description": "Template author"
+    },
+    "repository": {
+      "type": "string",
+      "description": "Template repository URL"
+    },
+    "coreSchemaVersion": {
+      "type": "string",
+      "description": "The core schema version this template implements (e.g., '1.0.0')",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Theme-specific configuration extensions supported by this template",
+      "properties": {
+        "footer": {
+          "type": "object",
+          "description": "Extended footer configuration support",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "layouts": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Supported footer layouts"
+            },
+            "socials": { "type": "boolean", "default": true },
+            "linkSections": { "type": "boolean", "default": true }
+          }
+        },
+        "theme": {
+          "type": "object",
+          "description": "Extended theme options",
+          "properties": {
+            "modes": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["light", "dark", "auto"] },
+              "description": "Supported theme modes"
+            },
+            "customColors": { "type": "boolean", "default": false },
+            "customFonts": { "type": "boolean", "default": false }
+          }
+        },
+        "landing": {
+          "type": "object",
+          "description": "Landing page support",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "hero": { "type": "boolean", "default": false },
+            "features": { "type": "boolean", "default": false }
+          }
+        },
+        "integrations": {
+          "type": "object",
+          "description": "Third-party integration support",
+          "properties": {
+            "analytics": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Supported analytics providers"
+            },
+            "feedback": { "type": "boolean", "default": false },
+            "copyPage": { "type": "boolean", "default": false }
+          }
+        },
+        "versioning": {
+          "type": "object",
+          "description": "Documentation versioning support",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "versionBanner": { "type": "boolean", "default": false }
+          }
+        }
+      },
+      "additionalProperties": {
+        "type": "object",
+        "description": "Custom extensions defined by the template"
+      }
+    },
+    "extensionSchema": {
+      "type": "string",
+      "description": "Path to JSON schema for template-specific extensions (relative to template root)"
+    }
+  }
+}