@litodocs/cli 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litodocs/cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Beautiful documentation sites from Markdown. Fast, simple, and open-source.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -5,6 +5,7 @@ import { devCommand } from "./commands/dev.js";
 import { ejectCommand } from "./commands/eject.js";
 import { initCommand } from "./commands/init.js";
 import { validateCommand } from "./commands/validate.js";
+import { checkLinksCommand } from "./commands/check-links.js";
 import { previewCommand } from "./commands/preview.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { infoCommand } from "./commands/info.js";
@@ -116,8 +117,21 @@ export async function cli() {
     .description("Validate docs-config.json configuration")
     .option("-i, --input <path>", "Path to the docs folder")
     .option("-q, --quiet", "Quiet mode for CI (exit code only)")
+    .option("--content", "Run content quality checks")
+    .option("--links", "Run broken link detection")
+    .option("--all", "Run all checks (config + content + links)")
+    .option("--strict", "Fail on warnings too (for CI)")
     .action(validateCommand);
 
+  // Check links
+  program
+    .command("check-links")
+    .description("Scan documentation for broken internal links")
+    .requiredOption("-i, --input <path>", "Path to the docs folder")
+    .option("--strict", "Exit with code 1 on broken links (CI)")
+    .option("-q, --quiet", "Quiet mode for CI (exit code only)")
+    .action(checkLinksCommand);
+
   // Preview production build
   program
     .command("preview")

package/src/commands/check-links.js

@@ -0,0 +1,75 @@
+import { resolve } from 'path';
+import { intro, outro, log, spinner } from '@clack/prompts';
+import pc from 'picocolors';
+import { checkLinks } from '../core/link-checker.js';
+
+/**
+ * Check links command — scan docs for broken internal links.
+ */
+export async function checkLinksCommand(options) {
+  try {
+    const inputPath = options.input ? resolve(options.input) : process.cwd();
+
+    // Quiet mode for CI
+    if (options.quiet) {
+      const result = await checkLinks(inputPath);
+      process.exit(result.brokenLinks.length > 0 ? 1 : 0);
+    }
+
+    console.clear();
+    intro(pc.inverse(pc.cyan(' Lito - Check Links ')));
+
+    const s = spinner();
+    s.start('Scanning documentation for broken links...');
+
+    const result = await checkLinks(inputPath);
+
+    if (result.brokenLinks.length === 0) {
+      s.stop(pc.green('All links are valid!'));
+      log.message('');
+      log.success(`Checked ${pc.bold(result.totalLinks)} links across ${pc.bold(result.checkedFiles)} files`);
+      log.message('');
+      outro(pc.green('No broken links found!'));
+      return;
+    }
+
+    s.stop(pc.yellow(`Found ${result.brokenLinks.length} broken link(s)`));
+    log.message('');
+
+    // Group broken links by file
+    const byFile = new Map();
+    for (const bl of result.brokenLinks) {
+      if (!byFile.has(bl.file)) byFile.set(bl.file, []);
+      byFile.get(bl.file).push(bl);
+    }
+
+    for (const [file, links] of byFile) {
+      log.message(pc.bold(pc.cyan(file)));
+      for (const bl of links) {
+        const label = bl.text ? ` (${pc.dim(bl.text)})` : '';
+        log.message(`  ${pc.red('✗')} ${bl.link}${label}`);
+        if (bl.suggestion) {
+          log.message(`    ${pc.dim('Did you mean:')} ${pc.green(bl.suggestion)}`);
+        }
+      }
+      log.message('');
+    }
+
+    log.message(pc.dim('─'.repeat(50)));
+    log.message(`${pc.bold('Summary:')} ${pc.red(result.brokenLinks.length + ' broken')} out of ${result.totalLinks} links in ${result.checkedFiles} files`);
+    log.message('');
+
+    if (options.strict) {
+      outro(pc.red('Link check failed (strict mode)'));
+      process.exit(1);
+    } else {
+      outro(pc.yellow('Link check complete with warnings'));
+    }
+  } catch (error) {
+    log.error(pc.red(error.message));
+    if (error.stack && !options.quiet) {
+      log.error(pc.gray(error.stack));
+    }
+    process.exit(1);
+  }
+}

package/src/commands/validate.js

@@ -3,6 +3,8 @@ import { resolve, join } from 'path';
 import { intro, outro, log, spinner } from '@clack/prompts';
 import pc from 'picocolors';
 import { validateConfig, isPortableConfig, getCoreConfigKeys, getExtensionKeys } from '../core/config-validator.js';
+import { lintContent } from '../core/content-linter.js';
+import { checkLinks } from '../core/link-checker.js';
 
 /**
  * Validate command - Validate docs-config.json
@@ -12,18 +14,41 @@ export async function validateCommand(options) {
     const inputPath = options.input ? resolve(options.input) : process.cwd();
     const configPath = join(inputPath, 'docs-config.json');
 
+    const runContent = options.content || options.all;
+    const runLinks = options.links || options.all;
+    const strict = options.strict || false;
+
     // Quick mode for CI - just exit with code
     if (options.quiet) {
+      let hasErrors = false;
+
+      // Config validation
       if (!existsSync(configPath)) {
         process.exit(1);
       }
       try {
         const config = JSON.parse(readFileSync(configPath, 'utf-8'));
         const result = validateConfig(config, inputPath, { silent: true });
-        process.exit(result.valid ? 0 : 1);
+        if (!result.valid) hasErrors = true;
+
+        // Content linting
+        if (runContent) {
+          const lint = await lintContent(inputPath, { config });
+          const hasLintErrors = lint.issues.some(i => i.severity === 'error');
+          const hasLintWarnings = lint.issues.some(i => i.severity === 'warning');
+          if (hasLintErrors || (strict && hasLintWarnings)) hasErrors = true;
+        }
+
+        // Link checking
+        if (runLinks) {
+          const linkResult = await checkLinks(inputPath);
+          if (linkResult.brokenLinks.length > 0) hasErrors = true;
+        }
       } catch (e) {
-        process.exit(1);
+        hasErrors = true;
       }
+
+      process.exit(hasErrors ? 1 : 0);
     }
 
     console.clear();
@@ -31,7 +56,7 @@ export async function validateCommand(options) {
 
     const s = spinner();
 
-    // Check if config file exists
+    // ── Config validation ──
     s.start('Looking for docs-config.json...');
 
     if (!existsSync(configPath)) {
@@ -113,7 +138,89 @@ export async function validateCommand(options) {
     }
 
     log.message('');
-    outro(pc.green('Validation complete!'));
+
+    // Track if any checks failed
+    let hasFailure = false;
+
+    // ── Content linting ──
+    if (runContent) {
+      log.message(pc.dim('─'.repeat(50)));
+      log.message('');
+      s.start('Linting documentation content...');
+
+      const lint = await lintContent(inputPath, { config });
+
+      const errors = lint.issues.filter(i => i.severity === 'error');
+      const warnings = lint.issues.filter(i => i.severity === 'warning');
+
+      if (lint.issues.length === 0) {
+        s.stop(pc.green(`Content is clean (${lint.totalFiles} files checked)`));
+      } else {
+        s.stop(pc.yellow(`Found ${lint.issues.length} issue(s) in ${lint.totalFiles} files`));
+        log.message('');
+
+        if (errors.length > 0) {
+          log.error(pc.bold(`Errors (${errors.length}):`));
+          for (const issue of errors) {
+            log.error(`  ${pc.red('✗')} ${pc.cyan(issue.file)}: ${issue.message} ${pc.dim(`[${issue.rule}]`)}`);
+          }
+          log.message('');
+          hasFailure = true;
+        }
+
+        if (warnings.length > 0) {
+          log.warn(pc.bold(`Warnings (${warnings.length}):`));
+          for (const issue of warnings) {
+            log.warn(`  ${pc.yellow('!')} ${pc.cyan(issue.file)}: ${issue.message} ${pc.dim(`[${issue.rule}]`)}`);
+          }
+          log.message('');
+          if (strict) hasFailure = true;
+        }
+      }
+    }
+
+    // ── Link checking ──
+    if (runLinks) {
+      log.message(pc.dim('─'.repeat(50)));
+      log.message('');
+      s.start('Checking for broken links...');
+
+      const linkResult = await checkLinks(inputPath);
+
+      if (linkResult.brokenLinks.length === 0) {
+        s.stop(pc.green(`All ${linkResult.totalLinks} links are valid (${linkResult.checkedFiles} files)`));
+      } else {
+        s.stop(pc.yellow(`Found ${linkResult.brokenLinks.length} broken link(s)`));
+        log.message('');
+
+        // Group by file
+        const byFile = new Map();
+        for (const bl of linkResult.brokenLinks) {
+          if (!byFile.has(bl.file)) byFile.set(bl.file, []);
+          byFile.get(bl.file).push(bl);
+        }
+
+        for (const [file, links] of byFile) {
+          log.message(`  ${pc.bold(pc.cyan(file))}`);
+          for (const bl of links) {
+            const label = bl.text ? ` (${pc.dim(bl.text)})` : '';
+            log.message(`    ${pc.red('✗')} ${bl.link}${label}`);
+            if (bl.suggestion) {
+              log.message(`      ${pc.dim('Did you mean:')} ${pc.green(bl.suggestion)}`);
+            }
+          }
+        }
+        log.message('');
+        hasFailure = true;
+      }
+    }
+
+    if (hasFailure) {
+      outro(pc.red('Validation complete with errors'));
+      process.exit(1);
+    } else {
+      outro(pc.green('Validation complete!'));
+    }
   } catch (error) {
     log.error(pc.red(error.message));
     if (error.stack && !options.quiet) {

package/src/core/config.js

@@ -102,6 +102,94 @@ export async function generateConfig(projectDir, options, frameworkConfig = null
     }
   }
 
+  // Inject llms.txt integration into astro.config.mjs
+  if (frameworkName === 'astro' && config.integrations?.llmsTxt?.enabled && config.metadata?.url) {
+    const astroConfigPath = join(projectDir, "astro.config.mjs");
+    if (await pathExists(astroConfigPath)) {
+      let content = await readFile(astroConfigPath, "utf-8");
+
+      // Add import after the last existing import line
+      const importLine = `import astroLlmsTxt from '@4hse/astro-llms-txt';`;
+      if (!content.includes(importLine)) {
+        const lines = content.split('\n');
+        let lastImportIdx = 0;
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].startsWith('import ')) lastImportIdx = i;
+        }
+        lines.splice(lastImportIdx + 1, 0, importLine);
+        content = lines.join('\n');
+      }
+
+      // Build the integration call
+      const llmsTitle = config.integrations.llmsTxt.title || config.metadata.name || 'Documentation';
+      const llmsDesc = config.integrations.llmsTxt.description || config.metadata.description || '';
+      const llmsConfig = `    astroLlmsTxt({
+      title: ${JSON.stringify(llmsTitle)},
+      description: ${JSON.stringify(llmsDesc)},
+      docSet: [
+        {
+          title: ${JSON.stringify(llmsTitle + ' - Full Documentation')},
+          description: ${JSON.stringify('Complete documentation content')},
+          url: '/llms-full.txt',
+          include: ['**'],
+          mainSelector: 'article',
+          ignoreSelectors: ['nav', '.sidebar', '.toc', 'footer', '.breadcrumbs'],
+        },
+        {
+          title: ${JSON.stringify(llmsTitle + ' - Structure')},
+          description: ${JSON.stringify('Documentation structure overview')},
+          url: '/llms-small.txt',
+          include: ['**'],
+          onlyStructure: true,
+          mainSelector: 'article',
+          ignoreSelectors: ['nav', '.sidebar', '.toc', 'footer', '.breadcrumbs'],
+        },
+      ],
+    }),`;
+
+      // Insert after sitemap() in integrations array
+      if (content.includes('sitemap(),')) {
+        content = content.replace(
+          'sitemap(),',
+          `sitemap(),\n${llmsConfig}`
+        );
+      } else {
+        // Fallback: insert at start of integrations array
+        content = content.replace(
+          'integrations: [',
+          `integrations: [\n${llmsConfig}`
+        );
+      }
+
+      await writeFile(astroConfigPath, content, "utf-8");
+    }
+  }
+
+  // Inject redirects into astro.config.mjs
+  if (frameworkName === 'astro' && config.redirects && Object.keys(config.redirects).length > 0) {
+    const astroConfigPath = join(projectDir, "astro.config.mjs");
+    if (await pathExists(astroConfigPath)) {
+      let content = await readFile(astroConfigPath, "utf-8");
+
+      // Build redirects object for Astro config
+      const redirectEntries = Object.entries(config.redirects).map(([source, dest]) => {
+        if (typeof dest === 'string') {
+          return `    '${source}': '${dest}'`;
+        }
+        return `    '${source}': { status: ${dest.status || 301}, destination: '${dest.destination}' }`;
+      });
+
+      const redirectsBlock = `  redirects: {\n${redirectEntries.join(',\n')}\n  },`;
+
+      content = content.replace(
+        "export default defineConfig({",
+        `export default defineConfig({\n${redirectsBlock}`
+      );
+
+      await writeFile(astroConfigPath, content, "utf-8");
+    }
+  }
+
   // Update vite.config.js for React/Vue frameworks
   if (['react', 'vue'].includes(frameworkName) && baseUrl && baseUrl !== "/") {
     const viteConfigPath = join(projectDir, "vite.config.js");

package/src/core/content-linter.js

@@ -0,0 +1,172 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { collectMarkdownFiles, parseFrontmatter, deriveSlug } from './doc-utils.js';
+
+/**
+ * @typedef {'error' | 'warning'} Severity
+ * @typedef {{ rule: string, severity: Severity, file: string, message: string }} LintIssue
+ * @typedef {{ issues: LintIssue[], totalFiles: number }} LintResult
+ */
+
+/**
+ * Run content quality checks on all markdown files in a docs folder.
+ *
+ * @param {string} docsPath - Root docs directory
+ * @param {object} [options]
+ * @param {object} [options.config] - Parsed docs-config.json (for orphan detection)
+ * @returns {Promise<LintResult>}
+ */
+export async function lintContent(docsPath, options = {}) {
+  const files = await collectMarkdownFiles(docsPath);
+  /** @type {LintIssue[]} */
+  const issues = [];
+
+  // Pre-compute title map for duplicate detection
+  /** @type {Map<string, string[]>} title → list of relative paths */
+  const titleMap = new Map();
+
+  // Pre-compute sidebar slugs for orphan detection
+  const sidebarSlugs = new Set();
+  if (options.config?.navigation?.sidebar) {
+    collectSidebarSlugs(options.config.navigation.sidebar, sidebarSlugs);
+  }
+
+  for (const file of files) {
+    const content = readFileSync(file.absolutePath, 'utf-8');
+    const { data, body } = parseFrontmatter(content);
+    const slug = deriveSlug(file.relativePath);
+
+    // ── missing-title ──
+    if (!data.title) {
+      issues.push({
+        rule: 'missing-title',
+        severity: 'warning',
+        file: file.relativePath,
+        message: 'No title in frontmatter',
+      });
+    }
+
+    // ── missing-description ──
+    if (!data.description) {
+      issues.push({
+        rule: 'missing-description',
+        severity: 'warning',
+        file: file.relativePath,
+        message: 'No description in frontmatter',
+      });
+    }
+
+    // ── empty-page ──
+    if (!body || body.trim().length === 0) {
+      issues.push({
+        rule: 'empty-page',
+        severity: 'error',
+        file: file.relativePath,
+        message: 'Page has no content body',
+      });
+    }
+
+    // ── long-title ──
+    if (data.title && data.title.length > 70) {
+      issues.push({
+        rule: 'long-title',
+        severity: 'warning',
+        file: file.relativePath,
+        message: `Title is ${data.title.length} characters (recommended max: 70 for SEO)`,
+      });
+    }
+
+    // ── missing-image ──
+    // Check markdown image references: ![alt](path)
+    const imageRegex = /!\[[^\]]*\]\(([^)]+)\)/g;
+    let imgMatch;
+    while ((imgMatch = imageRegex.exec(content)) !== null) {
+      const imgPath = imgMatch[1].split(/[?#]/)[0]; // strip query/fragment
+      if (!imgPath || /^(https?:|data:)/.test(imgPath)) continue;
+
+      // Resolve relative to file's directory or to docs root for absolute paths
+      let resolvedPath;
+      if (imgPath.startsWith('/')) {
+        // Could be in _images, _assets, or public
+        const candidates = [
+          join(docsPath, '_images', imgPath.slice(1)),
+          join(docsPath, '_assets', imgPath.slice(1)),
+          join(docsPath, 'public', imgPath.slice(1)),
+        ];
+        if (!candidates.some(c => existsSync(c))) {
+          issues.push({
+            rule: 'missing-image',
+            severity: 'error',
+            file: file.relativePath,
+            message: `Referenced image not found: ${imgPath}`,
+          });
+        }
+      } else {
+        resolvedPath = join(dirname(file.absolutePath), imgPath);
+        if (!existsSync(resolvedPath)) {
+          issues.push({
+            rule: 'missing-image',
+            severity: 'error',
+            file: file.relativePath,
+            message: `Referenced image not found: ${imgPath}`,
+          });
+        }
+      }
+    }
+
+    // ── Collect titles for duplicate check ──
+    if (data.title) {
+      const normalizedTitle = data.title.toLowerCase().trim();
+      if (!titleMap.has(normalizedTitle)) {
+        titleMap.set(normalizedTitle, []);
+      }
+      titleMap.get(normalizedTitle).push(file.relativePath);
+    }
+
+    // ── orphaned-page ──
+    if (sidebarSlugs.size > 0) {
+      // Only check content pages, not index pages or API pages
+      if (!sidebarSlugs.has(slug)) {
+        issues.push({
+          rule: 'orphaned-page',
+          severity: 'warning',
+          file: file.relativePath,
+          message: `Page is not linked in sidebar navigation (slug: ${slug})`,
+        });
+      }
+    }
+  }
+
+  // ── duplicate-title (post-pass) ──
+  for (const [title, paths] of titleMap) {
+    if (paths.length > 1) {
+      for (const p of paths) {
+        issues.push({
+          rule: 'duplicate-title',
+          severity: 'warning',
+          file: p,
+          message: `Duplicate title "${title}" also in: ${paths.filter(x => x !== p).join(', ')}`,
+        });
+      }
+    }
+  }
+
+  return { issues, totalFiles: files.length };
+}
+
+/**
+ * Recursively extract all href slugs from sidebar config.
+ */
+function collectSidebarSlugs(groups, slugSet) {
+  for (const group of groups) {
+    if (!group.items) continue;
+    for (const item of group.items) {
+      if (item.href) {
+        slugSet.add(item.href);
+      }
+      if (item.items) {
+        collectSidebarSlugs([{ items: item.items }], slugSet);
+      }
+    }
+  }
+}

package/src/core/doc-utils.js

@@ -0,0 +1,123 @@
+import { readdir, readFile, stat } from 'fs/promises';
+import { join, relative, extname, sep } from 'path';
+
+/** Folders that contain non-content files (assets, custom landing, etc.) */
+const EXCLUDED_FOLDERS = ['_assets', '_css', '_images', '_static', '_landing', '_navbar', '_footer', 'public', 'node_modules'];
+
+/** Files that are not doc pages */
+const EXCLUDED_FILES = ['docs-config.json', 'vercel.json', 'netlify.toml', 'README.md'];
+
+/**
+ * Recursively collect all .md and .mdx files under docsPath,
+ * respecting the same exclusion rules as sync.js.
+ *
+ * @param {string} docsPath - Root docs directory
+ * @returns {Promise<Array<{ absolutePath: string, relativePath: string }>>}
+ */
+export async function collectMarkdownFiles(docsPath) {
+  const results = [];
+
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      const rel = relative(docsPath, fullPath);
+      const topSegment = rel.split(sep)[0];
+
+      if (entry.isDirectory()) {
+        if (EXCLUDED_FOLDERS.includes(topSegment) || EXCLUDED_FOLDERS.includes(entry.name)) {
+          continue;
+        }
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        if (EXCLUDED_FILES.includes(entry.name)) continue;
+        const ext = extname(entry.name).toLowerCase();
+        if (ext === '.md' || ext === '.mdx') {
+          results.push({ absolutePath: fullPath, relativePath: rel });
+        }
+      }
+    }
+  }
+
+  await walk(docsPath);
+  return results;
+}
+
+/**
+ * Parse YAML-style frontmatter from markdown content.
+ * Returns { data: Record<string, string>, body: string }.
+ * Simple key: value parsing — handles title, description, etc.
+ *
+ * @param {string} content - Raw file content
+ * @returns {{ data: Record<string, any>, body: string }}
+ */
+export function parseFrontmatter(content) {
+  if (!content.startsWith('---')) {
+    return { data: {}, body: content };
+  }
+
+  const endIdx = content.indexOf('---', 3);
+  if (endIdx === -1) {
+    return { data: {}, body: content };
+  }
+
+  const fmBlock = content.substring(3, endIdx).trim();
+  const body = content.substring(endIdx + 3).trim();
+  const data = {};
+
+  for (const line of fmBlock.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.substring(0, colonIdx).trim();
+    let value = line.substring(colonIdx + 1).trim();
+
+    // Strip surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    if (key) data[key] = value;
+  }
+
+  return { data, body };
+}
+
+/**
+ * Convert a relative file path to a URL slug.
+ *
+ * Examples:
+ *   "getting-started/installation.md"  → "/getting-started/installation"
+ *   "introduction/index.mdx"           → "/introduction"
+ *   "index.md"                         → "/"
+ *
+ * @param {string} relativePath - Path relative to docsPath
+ * @returns {string}
+ */
+export function deriveSlug(relativePath) {
+  let slug = relativePath
+    .replace(/\.(md|mdx)$/, '')
+    .split(sep)
+    .join('/');
+
+  // Remove trailing /index
+  if (slug.endsWith('/index')) {
+    slug = slug.slice(0, -6);
+  }
+  if (slug === 'index') {
+    slug = '';
+  }
+
+  return '/' + slug;
+}
+
+/**
+ * Check if a URL is external (http/https, mailto, tel, etc.)
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isExternalUrl(url) {
+  return /^(https?:|mailto:|tel:|ftp:)/.test(url);
+}

package/src/core/landing-sync.js

@@ -13,6 +13,46 @@ const { copy, ensureDir, readFile, writeFile, pathExists, readJson } = pkg;
 import { join, relative, basename, extname } from 'path';
 import { readdir } from 'fs/promises';
 
+/**
+ * Add is:inline to all <script> and <style> tags in HTML so Astro ships
+ * them as-is. Without this, Astro treats scripts as ES modules (scoping
+ * declarations, breaking onclick handlers) and scopes styles (breaking
+ * global CSS like :root variables, animations, etc.).
+ */
+function inlineForAstro(html) {
+  // Add is:inline to <script> tags that don't already have it
+  html = html.replace(/<script(?![^>]*is:inline)([^>]*>)/gi, '<script is:inline$1');
+  // Add is:inline to <style> tags that don't already have is:inline or is:global
+  html = html.replace(/<style(?![^>]*is:(?:inline|global))([^>]*>)/gi, '<style is:inline$1');
+  return html;
+}
+
+/**
+ * Check if HTML is a full document (has <html> or <!doctype>).
+ * If so, extract head content, body content, and html/body attributes
+ * so we can merge them into the Astro template properly.
+ */
+function parseFullHtmlDocument(html) {
+  const isFullDoc = /<!doctype\s+html|<html[\s>]/i.test(html);
+  if (!isFullDoc) return null;
+
+  // Extract <html> tag attributes
+  const htmlTagMatch = html.match(/<html([^>]*)>/i);
+  const htmlAttrs = htmlTagMatch ? htmlTagMatch[1].trim() : '';
+
+  // Extract <head> inner content
+  const headMatch = html.match(/<head[^>]*>([\s\S]*)<\/head>/i);
+  const headContent = headMatch ? headMatch[1].trim() : '';
+
+  // Extract <body> tag attributes and inner content
+  const bodyTagMatch = html.match(/<body([^>]*)>/i);
+  const bodyAttrs = bodyTagMatch ? bodyTagMatch[1].trim() : '';
+  const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+  const bodyContent = bodyMatch ? bodyMatch[1].trim() : '';
+
+  return { htmlAttrs, headContent, bodyContent, bodyAttrs };
+}
+
 /**
  * Landing page types
  */
@@ -309,6 +349,9 @@ async function generateAstroLanding(projectDir, landingData) {
 
   let htmlContent = await readFile(join(sourcePath, mainHtml), 'utf-8');
 
+  // Make all <script> tags in the user's HTML pass through Astro untouched
+  htmlContent = inlineForAstro(htmlContent);
+
   // Read CSS files and write to a separate file
   let cssContent = '';
   for (const cssFile of cssFiles) {
@@ -327,7 +370,36 @@ async function generateAstroLanding(projectDir, landingData) {
     jsContent += `// ${jsFile}\n${js}\n\n`;
   }
 
-  // Determine header/footer: hidden ('__hidden__'), custom (string HTML), or default (null)
+  // Check if the user's HTML is a full document (has <html>, <head>, <body>)
+  const parsed = parseFullHtmlDocument(htmlContent);
+
+  let astroContent;
+
+  if (parsed) {
+    // Full HTML document: merge the user's head/body into the Astro page
+    // instead of nesting an entire HTML document inside another one.
+    astroContent = generateAstroFromFullDoc(parsed, { cssFiles, jsContent, navbarContent, footerContent });
+  } else {
+    // HTML fragment: wrap it in a full Astro page
+    astroContent = generateAstroFromFragment(htmlContent, { jsContent, navbarContent, footerContent });
+  }
+
+  // Write to index.astro
+  const indexPath = join(projectDir, 'src', 'pages', 'index.astro');
+  await writeFile(indexPath, astroContent, 'utf-8');
+
+  // Copy assets if they exist
+  await copyLandingAssets(sourcePath, projectDir);
+}
+
+/**
+ * Generate Astro page from a full HTML document.
+ * Extracts <head> and <body> content, preserves the user's structure.
+ */
+function generateAstroFromFullDoc(parsed, { cssFiles, jsContent, navbarContent, footerContent }) {
+  const { htmlAttrs, headContent, bodyContent, bodyAttrs } = parsed;
+
+  // Determine header/footer rendering
   const navbarIsHidden = navbarContent === '__hidden__';
   const footerIsHidden = footerContent === '__hidden__';
   const hasCustomNavbar = !navbarIsHidden && !!navbarContent;
@@ -338,16 +410,64 @@ async function generateAstroLanding(projectDir, landingData) {
   const headerRender = navbarIsHidden
     ? ''
     : hasCustomNavbar
-      ? `<header class="landing-custom-navbar">\n      ${navbarContent}\n    </header>`
+      ? `<header class="landing-custom-navbar">\n      ${inlineForAstro(navbarContent)}\n    </header>`
       : '<Header />';
   const footerRender = footerIsHidden
     ? ''
     : hasCustomFooter
-      ? `<footer class="landing-custom-footer">\n      ${footerContent}\n    </footer>`
+      ? `<footer class="landing-custom-footer">\n      ${inlineForAstro(footerContent)}\n    </footer>`
       : '<Footer />';
 
-  // Generate standalone Astro component
-  const astroContent = `---
+  return `---
+// Custom landing page - auto-generated by Lito CLI
+// Source: _landing/ folder (full HTML document)
+import '../styles/landing.css';
+${headerImport}
+${footerImport}
+---
+
+<!doctype html>
+<html ${htmlAttrs}>
+  <head>
+    ${headContent}
+  </head>
+  <body ${bodyAttrs}>
+    ${headerRender}
+
+    ${bodyContent}
+
+    ${footerRender}
+
+    ${jsContent ? `<script is:inline>\n${jsContent}\n</script>` : ''}
+  </body>
+</html>
+`;
+}
+
+/**
+ * Generate Astro page from an HTML fragment.
+ * Wraps it in a full Astro page with Lito's defaults.
+ */
+function generateAstroFromFragment(htmlContent, { jsContent, navbarContent, footerContent }) {
+  const navbarIsHidden = navbarContent === '__hidden__';
+  const footerIsHidden = footerContent === '__hidden__';
+  const hasCustomNavbar = !navbarIsHidden && !!navbarContent;
+  const hasCustomFooter = !footerIsHidden && !!footerContent;
+
+  const headerImport = navbarIsHidden || hasCustomNavbar ? '' : "import Header from '../components/Header.astro';";
+  const footerImport = footerIsHidden || hasCustomFooter ? '' : "import Footer from '../components/Footer.astro';";
+  const headerRender = navbarIsHidden
+    ? ''
+    : hasCustomNavbar
+      ? `<header class="landing-custom-navbar">\n      ${inlineForAstro(navbarContent)}\n    </header>`
+      : '<Header />';
+  const footerRender = footerIsHidden
+    ? ''
+    : hasCustomFooter
+      ? `<footer class="landing-custom-footer">\n      ${inlineForAstro(footerContent)}\n    </footer>`
+      : '<Footer />';
+
+  return `---
 // Custom landing page - auto-generated by Lito CLI
 // Source: _landing/ folder
 import '../styles/global.css';
@@ -388,17 +508,10 @@ const config = await getConfigFile();
 
     ${footerRender}
 
-    ${jsContent ? `<script>\n${jsContent}\n</script>` : ''}
+    ${jsContent ? `<script is:inline>\n${jsContent}\n</script>` : ''}
   </body>
 </html>
 `;
-
-  // Write to index.astro
-  const indexPath = join(projectDir, 'src', 'pages', 'index.astro');
-  await writeFile(indexPath, astroContent, 'utf-8');
-
-  // Copy assets if they exist
-  await copyLandingAssets(sourcePath, projectDir);
 }
 
 /**
@@ -708,12 +821,12 @@ async function generateAstroSectionsLanding(projectDir, landingData) {
   const headerRender = navbarIsHidden
     ? ''
     : hasCustomNavbar
-      ? `<header class="landing-custom-navbar">\n      ${navbarContent}\n    </header>`
+      ? `<header class="landing-custom-navbar">\n      ${inlineForAstro(navbarContent)}\n    </header>`
       : '<Header />';
   const footerRender = footerIsHidden
     ? ''
     : hasCustomFooter
-      ? `<footer class="landing-custom-footer">\n      ${footerContent}\n    </footer>`
+      ? `<footer class="landing-custom-footer">\n      ${inlineForAstro(footerContent)}\n    </footer>`
       : '<Footer />';
 
   const astroContent = `---

package/src/core/link-checker.js

@@ -0,0 +1,172 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { collectMarkdownFiles, deriveSlug, isExternalUrl } from './doc-utils.js';
+
+/**
+ * @typedef {{ file: string, link: string, text: string, suggestion?: string }} BrokenLink
+ * @typedef {{ brokenLinks: BrokenLink[], totalLinks: number, checkedFiles: number }} CheckResult
+ */
+
+/**
+ * Scan all markdown files for broken internal links.
+ *
+ * @param {string} docsPath - Root docs directory
+ * @param {object} [options]
+ * @returns {Promise<CheckResult>}
+ */
+export async function checkLinks(docsPath, options = {}) {
+  const files = await collectMarkdownFiles(docsPath);
+
+  // Build a set of all known slugs for resolution
+  const knownSlugs = new Set();
+  for (const file of files) {
+    knownSlugs.add(deriveSlug(file.relativePath));
+  }
+
+  /** @type {BrokenLink[]} */
+  const brokenLinks = [];
+  let totalLinks = 0;
+
+  // Regex patterns for extracting links
+  // Markdown links (excluding images which start with !)
+  const mdLinkRegex = /(?<!!)\[([^\]]*)\]\(([^)]+)\)/g;
+  // HTML/JSX href attributes
+  const hrefRegex = /href=["']([^"']+)["']/g;
+
+  for (const file of files) {
+    const content = readFileSync(file.absolutePath, 'utf-8');
+    const links = [];
+
+    // Extract markdown links
+    let match;
+    while ((match = mdLinkRegex.exec(content)) !== null) {
+      links.push({ text: match[1], url: match[2] });
+    }
+    mdLinkRegex.lastIndex = 0;
+
+    // Extract href links
+    while ((match = hrefRegex.exec(content)) !== null) {
+      links.push({ text: '', url: match[1] });
+    }
+    hrefRegex.lastIndex = 0;
+
+    for (const { text, url } of links) {
+      // Skip non-checkable links
+      if (!url) continue;
+      if (isExternalUrl(url)) continue;
+      if (url.startsWith('#')) continue; // anchor-only
+      if (url.startsWith('{') || url.includes('${')) continue; // template vars
+      if (url.startsWith('data:')) continue;
+
+      totalLinks++;
+
+      // Strip anchor fragment and query string
+      const cleanUrl = url.split(/[?#]/)[0];
+      if (!cleanUrl) continue;
+
+      // Normalize: ensure leading slash
+      const slug = cleanUrl.startsWith('/') ? cleanUrl : '/' + cleanUrl;
+
+      // Check if slug resolves to a known page
+      if (resolveSlug(slug, knownSlugs, docsPath)) continue;
+
+      // Check if it's a static asset (in _assets, _images, public)
+      if (resolveStaticAsset(slug, docsPath)) continue;
+
+      // Broken link — try to suggest a fix
+      const suggestion = findClosestSlug(slug, knownSlugs);
+
+      brokenLinks.push({
+        file: file.relativePath,
+        link: url,
+        text,
+        ...(suggestion ? { suggestion } : {}),
+      });
+    }
+  }
+
+  return { brokenLinks, totalLinks, checkedFiles: files.length };
+}
+
+/**
+ * Try to resolve a slug against known slugs.
+ * Checks exact match, with/without trailing slash, and index variants.
+ */
+function resolveSlug(slug, knownSlugs, docsPath) {
+  // Normalize trailing slash
+  const normalized = slug.endsWith('/') ? slug.slice(0, -1) : slug;
+  if (!normalized) return knownSlugs.has('/'); // root
+
+  if (knownSlugs.has(normalized)) return true;
+
+  // Maybe it's linking to a directory with an index file
+  if (knownSlugs.has(normalized + '/index')) return true;
+
+  // Check if the raw file exists (.md/.mdx)
+  const withoutSlash = normalized.startsWith('/') ? normalized.slice(1) : normalized;
+  const candidates = [
+    join(docsPath, withoutSlash + '.md'),
+    join(docsPath, withoutSlash + '.mdx'),
+    join(docsPath, withoutSlash, 'index.md'),
+    join(docsPath, withoutSlash, 'index.mdx'),
+  ];
+
+  return candidates.some(c => existsSync(c));
+}
+
+/**
+ * Check if a path resolves to a static asset.
+ */
+function resolveStaticAsset(slug, docsPath) {
+  const withoutSlash = slug.startsWith('/') ? slug.slice(1) : slug;
+  const candidates = [
+    join(docsPath, 'public', withoutSlash),
+    join(docsPath, '_assets', withoutSlash),
+    join(docsPath, '_images', withoutSlash),
+  ];
+  return candidates.some(c => existsSync(c));
+}
+
+/**
+ * Find the closest matching slug using simple string similarity (Levenshtein-like).
+ *
+ * @param {string} target
+ * @param {Set<string>} knownSlugs
+ * @returns {string|null}
+ */
+function findClosestSlug(target, knownSlugs) {
+  let bestMatch = null;
+  let bestScore = Infinity;
+
+  for (const slug of knownSlugs) {
+    const dist = levenshtein(target, slug);
+    if (dist < bestScore && dist <= Math.max(target.length, slug.length) * 0.4) {
+      bestScore = dist;
+      bestMatch = slug;
+    }
+  }
+
+  return bestMatch;
+}
+
+/**
+ * Simple Levenshtein distance.
+ */
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+
+  return dp[m][n];
+}