npm - @knowcode/doc-builder - Versions diffs - 1.4.25 → 1.5.1 - Mend

@knowcode/doc-builder 1.4.25 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/.claude/settings.local.json +2 -1
package/CHANGELOG.md +52 -0
package/README.md +57 -7
package/assets/404.html +115 -0
package/assets/js/main.js +23 -0
package/cli.js +251 -2
package/doc-builder.config.js +34 -0
package/html/404.html +115 -0
package/html/README.html +71 -5
package/html/claude-workflow-guide.html +71 -5
package/html/documentation-index.html +77 -5
package/html/guides/authentication-guide.html +77 -5
package/html/guides/documentation-standards.html +77 -5
package/html/guides/seo-guide.html +557 -0
package/html/guides/troubleshooting-guide.html +77 -5
package/html/index.html +71 -5
package/html/js/main.js +23 -0
package/html/robots.txt +5 -0
package/html/sitemap.xml +75 -0
package/html/vercel-cli-setup-guide.html +452 -0
package/html/vercel-first-time-setup-guide.html +419 -0
package/lib/config.js +39 -1
package/lib/core-builder.js +110 -5
package/lib/deploy.js +61 -2
package/lib/seo.js +359 -0
package/package.json +1 -1

package/html/vercel-first-time-setup-guide.html ADDED Viewed

@@ -0,0 +1,419 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough.">
+    <title>Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough - Doc Builder</title>
+    <meta name="author" content="Lindsay Smith">
+    <meta name="keywords" content="documentation, markdown, static site generator, vercel, notion-style, project, your, directory, name">
+    <meta name="robots" content="index, follow">
+    <link rel="canonical" href="https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html">
+    <!-- Open Graph / Facebook -->
+    <meta property="og:type" content="article">
+    <meta property="og:url" content="https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html">
+    <meta property="og:title" content="Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough - Doc Builder">
+    <meta property="og:description" content="Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough.">
+    <meta property="og:image" content="https://doc-builder-delta.vercel.app/og-default.png">
+    <meta property="og:site_name" content="Doc Builder">
+    <meta property="og:locale" content="en_US">
+    <!-- Twitter Card -->
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:site" content="@planbbackups">
+    <meta name="twitter:creator" content="@planbbackups">
+    <meta name="twitter:title" content="Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough - Doc Builder">
+    <meta name="twitter:description" content="Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough.">
+    <meta name="twitter:image" content="https://doc-builder-delta.vercel.app/og-default.png">
+    <!-- Fonts -->
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+    <!-- Icons -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
+    <!-- Mermaid -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
+    <!-- Styles -->
+    <link rel="stylesheet" href="/css/notion-style.css">
+    <!-- Favicon -->
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📚</text></svg>">
+    <script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "TechArticle",
+  "headline": "Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough",
+  "description": "Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough.",
+  "author": {
+    "@type": "Person",
+    "name": "Lindsay Smith"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Knowcode Ltd",
+    "url": "https://knowcode.tech"
+  },
+  "datePublished": "2025-07-21T20:39:06.497Z",
+  "dateModified": "2025-07-21T20:39:06.497Z",
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html"
+  },
+  "breadcrumb": {
+    "@type": "BreadcrumbList",
+    "itemListElement": [
+      {
+        "@type": "ListItem",
+        "position": 1,
+        "name": "Doc Builder",
+        "item": "https://doc-builder-delta.vercel.app"
+      },
+      {
+        "@type": "ListItem",
+        "position": 2,
+        "name": "Vercel First Time Setup Guide",
+        "item": "https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html"
+      }
+    ]
+  }
+}
+</script>
+</head>
+<body>
+    <!-- Header -->
+    <header class="header">
+        <div class="header-content">
+            <a href="/index.html" class="logo">Doc Builder</a>
+            <div class="header-actions">
+                <div class="deployment-info">
+                    <span class="deployment-date" title="Built with doc-builder v1.5.0">Last updated: Jul 21, 2025, 08:39 PM UTC</span>
+                </div>
+                <button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
+                    <i class="fas fa-moon"></i>
+                </button>
+                <button id="menu-toggle" class="menu-toggle" aria-label="Toggle menu">
+                    <i class="fas fa-bars"></i>
+                </button>
+            </div>
+        </div>
+    </header>
+    <!-- Preview Banner -->
+    <div id="preview-banner" class="preview-banner">
+        <div class="banner-content">
+            <i class="fas fa-exclamation-triangle banner-icon"></i>
+            <span class="banner-text">This documentation is a preview version - some content may be incomplete</span>
+            <button id="dismiss-banner" class="banner-dismiss" aria-label="Dismiss banner">
+                <i class="fas fa-times"></i>
+            </button>
+        </div>
+    </div>
+    <!-- Breadcrumbs -->
+    <nav class="breadcrumbs" id="breadcrumbs">
+        <!-- Breadcrumbs will be generated by JavaScript -->
+    </nav>
+    <!-- Main Content -->
+    <div class="main-wrapper">
+        <!-- Sidebar -->
+        <aside class="sidebar">
+            <div class="sidebar-header">
+                <div class="filter-box">
+                    <input type="text" placeholder="Filter items..." class="filter-input" id="nav-filter">
+                    <i class="fas fa-search filter-icon"></i>
+                </div>
+            </div>
+            <nav class="navigation">
+      <div class="nav-section" data-level="0">
+        <a class="nav-title expanded" href="/README.html"  >
+          <i class="fas fa-home"></i> Documentation
+        </a>
+        <div class="nav-content" >
+        <a href="/README.html" class="nav-item" data-tooltip="@knowcode/doc-builder."><i class="fas fa-file-alt"></i> Overview</a>
+        <a href="/claude-workflow-guide.html" class="nav-item" data-tooltip="This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a>
+        <a href="/documentation-index.html" class="nav-item" data-tooltip="This directory contains additional documentation for the @knowcode/doc-builder project, organized by topic and purpose."><i class="fas fa-file-alt"></i> Documentation Index</a>
+        <a href="/vercel-cli-setup-guide.html" class="nav-item" data-tooltip="This guide provides comprehensive instructions for installing and configuring the Vercel CLI across different operating systems and environments."><i class="fas fa-file-alt"></i> Vercel Cli Setup Guide</a>
+        <a href="/vercel-first-time-setup-guide.html" class="nav-item active" data-tooltip="This guide provides a detailed explanation of every prompt you&#039;ll encounter during the first-time Vercel setup process when using."><i class="fas fa-file-alt"></i> Vercel First Time Setup Guide</a></div></div>
+      <div class="nav-section" data-level="1">
+        <a class="nav-title collapsible" href="#" data-target="nav-guides-1" >
+          <i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Guides
+        </a>
+        <div class="nav-content collapsed" id="nav-guides-1">
+        <a href="/guides/authentication-guide.html" class="nav-item" data-tooltip="This guide explains how to configure and use the built-in authentication feature in @knowcode/doc-builder to protect your documentation with basic..."><i class="fas fa-file-alt"></i> Authentication Guide</a>
+        <a href="/guides/documentation-standards.html" class="nav-item" data-tooltip="This document defines the documentation standards and conventions for the @knowcode/doc-builder project."><i class="fas fa-file-alt"></i> Documentation Standards</a>
+        <a href="/guides/seo-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features to help your documentation rank better in search results and..."><i class="fas fa-file-alt"></i> Seo Guide</a>
+        <a href="/guides/troubleshooting-guide.html" class="nav-item" data-tooltip="This guide helps you resolve common issues when using @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Troubleshooting Guide</a></div></div>
+            </nav>
+            <div class="resize-handle"></div>
+        </aside>
+        <!-- Content Area -->
+        <main class="content">
+            <div class="content-inner">
+                <h1>Vercel First-Time Setup Guide - Complete Prompt-by-Prompt Walkthrough</h1>
+<p><strong>Generated</strong>: 2025-07-21 20:45 UTC<br><strong>Status</strong>: Complete<br><strong>Verified</strong>: ✅</p>
+<h2>Overview</h2>
+<p>This guide provides a detailed explanation of every prompt you&#39;ll encounter during the first-time Vercel setup process when using <code>@knowcode/doc-builder deploy</code>. Understanding these prompts helps avoid common configuration errors and ensures successful deployment.</p>
+<h2>Pre-Setup Prompts (doc-builder specific)</h2>
+<p>Before Vercel CLI starts, doc-builder asks several configuration questions:</p>
+<h3>1. Project Name Prompt</h3>
+<pre><code>? What is your project name? › my-docs
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>This becomes your Vercel project identifier</li>
+<li>It will form part of your deployment URL: <code>project-name.vercel.app</code></li>
+<li>Must be lowercase, alphanumeric with hyphens only</li>
+<li>Auto-generated from your site name with special characters removed</li>
+</ul>
+<p><strong>Best practice</strong>: </p>
+<ul>
+<li>Keep it short and memorable</li>
+<li>Use hyphens instead of spaces</li>
+<li>Example: <code>my-docs</code>, <code>company-docs</code>, <code>api-reference</code></li>
+</ul>
+<h3>2. Custom Production URL</h3>
+<pre><code>? Custom production URL (optional)? ›
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Leave empty for auto-detection (recommended for new projects)</li>
+<li>Or enter your custom domain/alias if you already have one</li>
+<li>Can be a full URL or just the domain</li>
+</ul>
+<p><strong>Examples</strong>:</p>
+<ul>
+<li>Empty (press Enter) - Vercel will auto-assign</li>
+<li><code>docs.mycompany.com</code> - Custom domain</li>
+<li><code>my-docs-v2.vercel.app</code> - Specific Vercel subdomain</li>
+</ul>
+<h3>3. Framework Preset</h3>
+<pre><code>? Which framework preset? › - Use arrow-keys. Return to submit.
+❯   Other (Static HTML)
+    Next.js
+    Vite
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Determines build settings and optimizations</li>
+<li><strong>ALWAYS choose &quot;Other (Static HTML)&quot;</strong> for doc-builder</li>
+<li>This ensures Vercel treats your docs as pre-built static files</li>
+</ul>
+<p><strong>Why this matters</strong>:</p>
+<ul>
+<li>Wrong selection can trigger unwanted build processes</li>
+<li>May cause deployment failures or missing files</li>
+</ul>
+<h3>4. Public Access</h3>
+<pre><code>? Make the deployment publicly accessible? › (Y/n)
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li><strong>Yes (Y)</strong>: Anyone with the URL can view your docs</li>
+<li><strong>No (n)</strong>: Only team members can access (requires Vercel login)</li>
+</ul>
+<p><strong>Considerations</strong>:</p>
+<ul>
+<li>Choose Yes for public documentation</li>
+<li>Choose No for internal/private docs</li>
+<li>Can be changed later in Vercel dashboard</li>
+</ul>
+<h2>Vercel CLI Link Process</h2>
+<p>After the initial configuration, Vercel CLI takes over with its own prompts:</p>
+<h3>5. Directory Confirmation</h3>
+<pre><code>? Set up and deploy &quot;~/Documents/.../html&quot;? [Y/n]
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Vercel is asking to deploy from the current directory</li>
+<li>This should show your <code>html</code> output directory path</li>
+<li><strong>ALWAYS answer YES</strong></li>
+</ul>
+<p><strong>Common mistake</strong>: </p>
+<ul>
+<li>If you see a different path, you may be running from wrong directory</li>
+<li>Should be run from project root, not from inside <code>html</code> folder</li>
+</ul>
+<h3>6. Scope Selection</h3>
+<pre><code>? Which scope should contain your project? ›
+❯   Lindsay Smith (lindsay-smith)
+    Another Team (team-slug)
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Determines which account/team owns the project</li>
+<li>Personal accounts show as &quot;Your Name (username)&quot;</li>
+<li>Team accounts show as &quot;Team Name (team-slug)&quot;</li>
+<li><strong>Select your personal account for individual projects</strong></li>
+</ul>
+<p><strong>When to use teams</strong>:</p>
+<ul>
+<li>Collaborative projects</li>
+<li>Company/organization deployments</li>
+<li>Shared billing and permissions</li>
+</ul>
+<h3>7. Existing Project Detection</h3>
+<pre><code>? Found project &quot;lindsay-1340s-projects/html&quot;. Link to it? [Y/n]
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Vercel found a project with similar name/path</li>
+<li>This is often a <strong>false match</strong> - generic names like &quot;html&quot; are common</li>
+<li><strong>ALWAYS answer NO unless you&#39;re 100% sure it&#39;s YOUR project</strong></li>
+</ul>
+<p><strong>Why this happens</strong>:</p>
+<ul>
+<li>Vercel searches for projects with matching directory names</li>
+<li>Common folder names (html, docs, dist) often match other projects</li>
+<li>The suggested project usually belongs to someone else</li>
+</ul>
+<h3>8. Link to Different Project</h3>
+<pre><code>? Link to different existing project? [Y/n]
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li><strong>Yes (Y)</strong>: You have an existing Vercel project to connect to</li>
+<li><strong>No (n)</strong>: Create a brand new project</li>
+</ul>
+<p><strong>When to answer YES</strong>:</p>
+<ul>
+<li>You&#39;ve deployed before and want to update existing project</li>
+<li>You created a project in Vercel dashboard first</li>
+<li>You&#39;re reconnecting after deleting <code>.vercel</code> folder</li>
+</ul>
+<p><strong>When to answer NO</strong>:</p>
+<ul>
+<li>First time deploying this documentation</li>
+<li>Want a fresh project with new URL</li>
+<li>Previous project had configuration issues</li>
+</ul>
+<h3>9A. Existing Project Name (if answered YES to #8)</h3>
+<pre><code>? What&#39;s the name of your existing project? ›
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Enter the exact name of your existing Vercel project</li>
+<li>Must match the project name in your Vercel dashboard</li>
+<li>Case-sensitive</li>
+</ul>
+<p><strong>How to find project name</strong>:</p>
+<ol>
+<li>Go to <a href="https://vercel.com/dashboard">https://vercel.com/dashboard</a></li>
+<li>Look for your project in the list</li>
+<li>Use the exact name shown</li>
+</ol>
+<h3>9B. New Project Name (if answered NO to #8)</h3>
+<pre><code>? What is your project name? › my-docs
+</code></pre>
+<p><strong>What it means</strong>: ✅</p>
+<ul>
+<li>Creates a new project with this name</li>
+<li>Will become your default URL: <code>project-name.vercel.app</code></li>
+<li>Must be unique across all Vercel projects</li>
+</ul>
+<p><strong>Best practices</strong>:</p>
+<ul>
+<li>Use same name as initial prompt for consistency</li>
+<li>Keep it descriptive but concise</li>
+<li>Avoid generic names like &quot;docs&quot; or &quot;html&quot;</li>
+</ul>
+<h2>Critical Post-Setup Configuration</h2>
+<h3>Root Directory Warning</h3>
+<p>After linking, you may see an error about &quot;html/html does not exist&quot;. This means Vercel incorrectly set the Root Directory.</p>
+<p><strong>The Problem</strong>: ❌</p>
+<ul>
+<li>Vercel sometimes auto-sets Root Directory to &quot;html&quot;</li>
+<li>But we&#39;re already deploying FROM the html directory</li>
+<li>This creates a path like <code>html/html</code> which doesn&#39;t exist</li>
+</ul>
+<p><strong>The Solution</strong>: ✅</p>
+<ol>
+<li>Go to your project settings: <code>https://vercel.com/[your-project]/settings</code></li>
+<li>Find &quot;Root Directory&quot; under &quot;Build &amp; Development Settings&quot;</li>
+<li><strong>DELETE any value</strong> - leave it completely empty</li>
+<li>Click &quot;Save&quot;</li>
+</ol>
+<h3>Build Settings Configuration</h3>
+<p>Vercel may also auto-detect build commands that interfere with static deployment.</p>
+<p><strong>Check these settings</strong>:</p>
+<ul>
+<li><strong>Build Command</strong>: Should be empty</li>
+<li><strong>Output Directory</strong>: Should be empty or &quot;./&quot;</li>
+<li><strong>Install Command</strong>: Should be empty</li>
+<li><strong>Development Command</strong>: Should be empty</li>
+</ul>
+<p><strong>If any have values</strong>:</p>
+<ol>
+<li>Clear them completely</li>
+<li>Save changes</li>
+<li>Redeploy</li>
+</ol>
+<h2>Deployment Protection Settings</h2>
+<p>For public documentation:</p>
+<ol>
+<li>Navigate to <strong>Project Settings &gt; General</strong></li>
+<li>Find <strong>&quot;Deployment Protection&quot;</strong> under Security</li>
+<li>Set to <strong>&quot;Disabled&quot;</strong> for public access</li>
+<li>Or configure password protection if needed</li>
+</ol>
+<h2>Common Issues and Solutions</h2>
+<h3>Issue 1: &quot;Cannot read properties of null&quot;</h3>
+<p><strong>Cause</strong>: Build settings conflict<br><strong>Solution</strong>: Clear all build settings in Vercel dashboard</p>
+<h3>Issue 2: &quot;Directory html/html does not exist&quot;</h3>
+<p><strong>Cause</strong>: Root Directory misconfiguration<br><strong>Solution</strong>: Remove &quot;html&quot; from Root Directory setting</p>
+<h3>Issue 3: &quot;404 errors on deployment&quot;</h3>
+<p><strong>Cause</strong>: Files not in correct location<br><strong>Solution</strong>: Ensure you ran <code>doc-builder build</code> before deploying</p>
+<h3>Issue 4: &quot;Permission denied&quot;</h3>
+<p><strong>Cause</strong>: Not logged into Vercel<br><strong>Solution</strong>: Run <code>vercel login</code> first</p>
+<h2>Quick Reference Checklist</h2>
+<pre><code>✅ 1. Project name? → your-project-name
+✅ 2. Custom URL? → [Leave empty or enter domain]
+✅ 3. Framework? → Other (Static HTML)
+✅ 4. Public? → Yes (for public docs)
+✅ 5. Set up ~/html? → YES
+✅ 6. Which scope? → Your account
+✅ 7. Found project &quot;xyz/html&quot;? → NO
+✅ 8. Link to different project? → YES/NO (your choice)
+✅ 9. Project name? → [Based on #8 answer]
+✅ 10. Check Root Directory → Must be EMPTY
+</code></pre>
+<h2>Pro Tips</h2>
+<ol>
+<li><strong>Save your answers</strong>: Document your choices for future reference</li>
+<li><strong>Verify URLs</strong>: Always check the deployment URL matches expectations</li>
+<li><strong>Use unique names</strong>: Avoid conflicts with generic project names</li>
+<li><strong>Check settings</strong>: Always verify Vercel dashboard settings after setup</li>
+<li><strong>Keep it simple</strong>: Don&#39;t add build commands for static sites</li>
+</ol>
+<h2>Next Steps</h2>
+<p>After successful setup:</p>
+<ol>
+<li>Your docs are live at <code>https://[project-name].vercel.app</code></li>
+<li>Future deploys just need: <code>npx @knowcode/doc-builder deploy</code></li>
+<li>Add custom domain in Vercel dashboard if needed</li>
+<li>Configure team access if required</li>
+</ol>
+<hr>
+<p>This guide covers every prompt in the Vercel first-time setup process. For additional help, refer to the main <a href="./vercel-cli-setup-guide.md">Vercel CLI Setup Guide</a>.</p>
+            </div>
+        </main>
+    </div>
+    <!-- Scripts -->
+    <script src="/js/main.js"></script>
+</body>
+</html>

package/lib/config.js CHANGED Viewed

@@ -45,6 +45,25 @@ const defaultConfig = {
   deployment: {
     platform: 'vercel',
     outputDirectory: 'html'
+  },
+  // SEO configuration
+  seo: {
+    enabled: true,
+    siteUrl: '',  // Required for proper SEO
+    author: '',
+    twitterHandle: '',
+    language: 'en-US',
+    keywords: [],
+    organization: {
+      name: '',
+      url: '',
+      logo: ''
+    },
+    ogImage: '',  // Default Open Graph image
+    generateSitemap: true,
+    generateRobotsTxt: true,
+    customMetaTags: []
   }
 };
@@ -133,7 +152,26 @@ const notionInspiredPreset = {
     'mcp',
     'team',
     'thought-leadership'
-  ]
+  ],
+  // SEO configuration for notion preset
+  seo: {
+    enabled: true,
+    siteUrl: '',
+    author: '',
+    twitterHandle: '',
+    language: 'en-US',
+    keywords: ['documentation', 'api', 'guide'],
+    organization: {
+      name: '',
+      url: '',
+      logo: ''
+    },
+    ogImage: '',
+    generateSitemap: true,
+    generateRobotsTxt: true,
+    customMetaTags: []
+  }
 };
 /**

package/lib/core-builder.js CHANGED Viewed

@@ -2,6 +2,15 @@ const fs = require('fs-extra');
 const path = require('path');
 const marked = require('marked');
 const chalk = require('chalk');
+const {
+  generateMetaTags,
+  generateJSONLD,
+  generateDescription,
+  extractKeywords,
+  generateBreadcrumbs,
+  generateSitemap,
+  generateRobotsTxt
+} = require('./seo');
 // Configure marked options
 marked.setOptions({
@@ -180,7 +189,7 @@ function processMarkdownContent(content) {
 }
 // Generate HTML from template
-function generateHTML(title, content, navigation, currentPath = '', config = {}) {
+function generateHTML(title, content, navigation, currentPath = '', config = {}, originalContent = '') {
   const depth = currentPath.split('/').filter(p => p).length;
   const relativePath = depth > 0 ? '../'.repeat(depth) : '';
@@ -191,13 +200,63 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
   const packageJson = require('../package.json');
   const docBuilderVersion = packageJson.version;
+  // SEO preparation
+  let seoTags = '';
+  let jsonLd = '';
+  if (config.seo?.enabled && config.seo?.siteUrl) {
+    // Generate page URL
+    const pageUrl = `${config.seo.siteUrl}/${currentPath}`;
+    // Extract or generate description
+    const pageDescription = generateDescription(originalContent || content) || siteDescription;
+    // Extract keywords from content
+    const contentKeywords = extractKeywords(originalContent || content, 5);
+    const keywords = [...new Set([...(config.seo.keywords || []), ...contentKeywords])];
+    // Generate breadcrumbs
+    const breadcrumbs = generateBreadcrumbs(currentPath, config.seo.siteUrl, siteName);
+    // Generate meta tags
+    seoTags = generateMetaTags({
+      title: `${title} - ${siteName}`,
+      description: pageDescription,
+      url: pageUrl,
+      author: config.seo.author,
+      keywords: keywords,
+      twitterHandle: config.seo.twitterHandle,
+      ogImage: config.seo.ogImage,
+      siteName: siteName,
+      language: config.seo.language,
+      type: 'article'
+    });
+    // Generate JSON-LD
+    const now = new Date().toISOString();
+    jsonLd = generateJSONLD({
+      title: title,
+      description: pageDescription,
+      url: pageUrl,
+      author: config.seo.author,
+      siteName: siteName,
+      datePublished: now,
+      dateModified: now,
+      breadcrumbs: breadcrumbs,
+      organization: config.seo.organization,
+      type: 'TechArticle'
+    });
+  }
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="description" content="${siteDescription}">
-    <title>${title} - ${siteName}</title>
+    <meta name="description" content="${escapeHtml(generateDescription(originalContent || content) || siteDescription)}">
+    <title>${escapeHtml(title)} - ${escapeHtml(siteName)}</title>
+${seoTags}
     <!-- Fonts -->
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
@@ -213,6 +272,8 @@ function generateHTML(title, content, navigation, currentPath = '', config = {})
     <!-- Favicon -->
     <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📚</text></svg>">
+    ${jsonLd}
 </head>
 <body>
     <!-- Header -->
@@ -534,8 +595,8 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config) {
   // Build navigation
   const navigation = buildNavigationStructure(allFiles, urlPath);
-  // Generate full HTML
-  const html = generateHTML(title, htmlContent, navigation, urlPath, config);
+  // Generate full HTML (pass original content for SEO)
+  const html = generateHTML(title, htmlContent, navigation, urlPath, config, content);
   // Write file
   await fs.ensureDir(path.dirname(outputPath));
@@ -639,6 +700,13 @@ async function buildDocumentation(config) {
     await createAuthPages(outputDir, config);
   }
+  // Copy 404.html for handling .md redirects
+  const notFoundSource = path.join(assetsDir, '404.html');
+  if (fs.existsSync(notFoundSource)) {
+    await fs.copy(notFoundSource, path.join(outputDir, '404.html'), { overwrite: true });
+    console.log(chalk.green('✅ Copied 404.html for .md link handling'));
+  }
   // Create index.html from index.html, README.html, or generate default
   const indexPath = path.join(outputDir, 'index.html');
   const indexSourcePath = path.join(outputDir, 'index.html'); // from index.md
@@ -735,6 +803,43 @@ async function buildDocumentation(config) {
     console.log(chalk.red(`  ❌ index.html is MISSING at: ${indexPath}`));
   }
+  // Generate SEO files if enabled
+  if (config.seo?.enabled && config.seo?.siteUrl) {
+    console.log(chalk.blue('\n🔍 Generating SEO files...'));
+    // Collect all HTML files for sitemap
+    const pages = [];
+    const walkDir = (dir, baseDir = '') => {
+      const items = fs.readdirSync(dir);
+      items.forEach(item => {
+        const fullPath = path.join(dir, item);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+          walkDir(fullPath, path.join(baseDir, item));
+        } else if (item.endsWith('.html') && !item.includes('login') && !item.includes('logout')) {
+          pages.push({
+            path: baseDir ? path.join(baseDir, item) : item,
+            modified: stat.mtime
+          });
+        }
+      });
+    };
+    walkDir(outputDir);
+    // Generate sitemap if enabled
+    if (config.seo.generateSitemap) {
+      await generateSitemap(pages, config.seo.siteUrl, outputDir);
+    }
+    // Generate robots.txt if enabled
+    if (config.seo.generateRobotsTxt) {
+      await generateRobotsTxt(config.seo.siteUrl, outputDir, {
+        hasAuthentication: config.features?.authentication
+      });
+    }
+  }
   console.log(chalk.green('✅ Documentation build complete!'));
 }