@litodocs/cli 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litodocs/cli",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Beautiful documentation sites from Markdown. Fast, simple, and open-source.",
   "main": "src/index.js",
   "type": "module",

package/src/cli.js

@@ -20,7 +20,7 @@ export async function cli() {
     .description(
       "Beautiful documentation sites from Markdown. Fast, simple, and open-source."
     )
-    .version("0.5.2");
+    .version("0.6.0");
 
   program
     .command("build")

package/src/core/config-sync.js

@@ -2,6 +2,7 @@ import pkg from 'fs-extra';
 const { readFile, writeFile, pathExists } = pkg;
 import { join } from 'path';
 import { readdir } from 'fs/promises';
+import { validateConfig } from './config-validator.js';
 
 /**
  * Auto-generates navigation structure from docs folder
@@ -70,8 +71,11 @@ export async function generateNavigationFromDocs(docsPath) {
 
 /**
  * Merges user config with auto-generated navigation
+ * @param {object} options - Sync options
+ * @param {boolean} options.validate - Whether to validate the config (default: true)
  */
-export async function syncDocsConfig(projectDir, docsPath, userConfigPath) {
+export async function syncDocsConfig(projectDir, docsPath, userConfigPath, options = {}) {
+  const { validate = true } = options;
   const configPath = join(projectDir, 'docs-config.json');
 
   // Read base config from template
@@ -80,6 +84,16 @@ export async function syncDocsConfig(projectDir, docsPath, userConfigPath) {
   // If user has a custom config, merge it
   if (userConfigPath && await pathExists(userConfigPath)) {
     const userConfig = JSON.parse(await readFile(userConfigPath, 'utf-8'));
+
+    // Validate user config before merging (only core config is validated)
+    if (validate) {
+      const validationResult = validateConfig(userConfig, projectDir);
+      if (!validationResult.valid) {
+        const errorMessages = validationResult.errors.map(e => `${e.path}: ${e.message}`).join('\n  ');
+        throw new Error(`Configuration validation failed:\n  ${errorMessages}`);
+      }
+    }
+
     config = deepMerge(config, userConfig);
   }
 
@@ -90,6 +104,8 @@ export async function syncDocsConfig(projectDir, docsPath, userConfigPath) {
 
   // Write merged config
   await writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+  return { config };
 }
 
 function formatLabel(str) {

package/src/core/config-validator.js

@@ -0,0 +1,229 @@
+/**
+ * Configuration Validator
+ *
+ * Validates user docs-config.json against the core schema.
+ * Core config is strictly validated - extensions are always allowed
+ * (templates simply ignore what they don't support).
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import pc from 'picocolors';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Core schema defines portable config across all templates
+const CORE_SCHEMA_PATH = join(__dirname, '../schema/core-schema.json');
+
+// Core config keys that all templates must support
+const CORE_CONFIG_KEYS = [
+  'metadata',
+  'branding',
+  'navigation',
+  'search',
+  'seo',
+  'i18n',
+  'assets'
+];
+
+// Extension keys that are template-specific (optional, never cause errors)
+const EXTENSION_KEYS = [
+  'footer',
+  'theme',
+  'landing',
+  'integrations',
+  'versioning'
+];
+
+/**
+ * Load the core schema
+ */
+function loadCoreSchema() {
+  if (!existsSync(CORE_SCHEMA_PATH)) {
+    return null;
+  }
+  return JSON.parse(readFileSync(CORE_SCHEMA_PATH, 'utf-8'));
+}
+
+/**
+ * Load template manifest from project directory
+ */
+export function loadTemplateManifest(projectDir) {
+  const manifestPath = join(projectDir, 'template.json');
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Validate configuration against core schema (basic validation)
+ * Only validates REQUIRED fields and types - extensions are always allowed.
+ */
+function validateCoreConfig(config, schema) {
+  const errors = [];
+
+  // Check required fields
+  if (schema.required) {
+    for (const field of schema.required) {
+      if (!(field in config)) {
+        errors.push({
+          path: field,
+          message: `Required field '${field}' is missing`
+        });
+      }
+    }
+  }
+
+  // Check metadata.name is required
+  if (config.metadata && !config.metadata.name) {
+    errors.push({
+      path: 'metadata.name',
+      message: "Required field 'metadata.name' is missing"
+    });
+  }
+
+  // Validate types for core fields
+  if (config.metadata && typeof config.metadata !== 'object') {
+    errors.push({
+      path: 'metadata',
+      message: "'metadata' must be an object"
+    });
+  }
+
+  if (config.navigation?.sidebar && !Array.isArray(config.navigation.sidebar)) {
+    errors.push({
+      path: 'navigation.sidebar',
+      message: "'navigation.sidebar' must be an array"
+    });
+  }
+
+  if (config.navigation?.navbar?.links && !Array.isArray(config.navigation.navbar.links)) {
+    errors.push({
+      path: 'navigation.navbar.links',
+      message: "'navigation.navbar.links' must be an array"
+    });
+  }
+
+  // Validate sidebar items structure
+  if (config.navigation?.sidebar && Array.isArray(config.navigation.sidebar)) {
+    config.navigation.sidebar.forEach((group, i) => {
+      if (!group.label) {
+        errors.push({
+          path: `navigation.sidebar[${i}].label`,
+          message: `Sidebar group at index ${i} is missing required 'label' field`
+        });
+      }
+      if (group.items && !Array.isArray(group.items)) {
+        errors.push({
+          path: `navigation.sidebar[${i}].items`,
+          message: `Sidebar group '${group.label}' items must be an array`
+        });
+      }
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Validate user configuration
+ *
+ * Only validates core config structure. Extensions are always allowed -
+ * templates simply ignore what they don't support.
+ *
+ * @param {object} config - User's docs-config.json content
+ * @param {string} projectDir - Path to the project directory
+ * @param {object} options - Validation options
+ * @param {boolean} options.silent - If true, don't print anything
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+export function validateConfig(config, projectDir, options = {}) {
+  const { silent = false } = options;
+
+  const coreSchema = loadCoreSchema();
+
+  // Only validate core config - extensions are always allowed
+  const coreErrors = coreSchema ? validateCoreConfig(config, coreSchema) : [];
+
+  const result = {
+    valid: coreErrors.length === 0,
+    errors: coreErrors,
+    manifest: loadTemplateManifest(projectDir)
+  };
+
+  if (!silent && coreErrors.length > 0) {
+    printValidationErrors(coreErrors);
+  }
+
+  return result;
+}
+
+/**
+ * Print validation errors to console
+ */
+function printValidationErrors(errors) {
+  console.log(pc.red('\n✗ Configuration validation failed:\n'));
+  for (const error of errors) {
+    console.log(pc.red(`  • ${error.path}: ${error.message}`));
+  }
+  console.log('');
+}
+
+/**
+ * Get list of portable (core) config keys
+ */
+export function getCoreConfigKeys() {
+  return [...CORE_CONFIG_KEYS];
+}
+
+/**
+ * Get list of extension config keys
+ */
+export function getExtensionKeys() {
+  return [...EXTENSION_KEYS];
+}
+
+/**
+ * Extract only core config from a full config object
+ */
+export function extractCoreConfig(config) {
+  const coreConfig = {};
+  for (const key of CORE_CONFIG_KEYS) {
+    if (key in config) {
+      coreConfig[key] = config[key];
+    }
+  }
+  return coreConfig;
+}
+
+/**
+ * Extract only extension config from a full config object
+ */
+export function extractExtensionConfig(config) {
+  const extensionConfig = {};
+  for (const key of EXTENSION_KEYS) {
+    if (key in config) {
+      extensionConfig[key] = config[key];
+    }
+  }
+  return extensionConfig;
+}
+
+/**
+ * Check if config is portable (uses only core config)
+ * Useful for users who want to ensure their config works with any template.
+ */
+export function isPortableConfig(config) {
+  for (const key of EXTENSION_KEYS) {
+    if (key in config) {
+      return false;
+    }
+  }
+  return true;
+}

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)"
+    }
+  }
+}