@knowcode/doc-builder 1.5.4 → 1.5.5

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to @knowcode/doc-builder will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.5] - 2025-07-22
+
+### Added
+- **Front Matter Support**: Parse YAML front matter for page-specific SEO customization
+- **SEO Check Command**: New `seo-check` command to analyze and report SEO issues
+- **Smart Description Extraction**: Intelligent extraction of intro paragraphs for better descriptions
+- **Enhanced Title Generation**: SEO-optimized titles with customizable templates
+- **Page-specific Keywords**: Support for front matter keywords plus auto-extraction
+- **Comprehensive SEO Guide**: Detailed documentation for SEO optimization
+
+### Changed
+- Improved `generateDescription` with smart mode for better meta descriptions
+- Title generation now respects 50-60 character limit with smart truncation
+- Keywords can be defined per-page via front matter
+- SEO configuration expanded with new options
+
+### Features
+- **Front Matter SEO**: Add custom title, description, and keywords per page
+- **Title Templates**: Configure title format with `{pageTitle} | {siteName}` patterns
+- **Auto Keywords**: Automatically extract relevant keywords from content
+- **SEO Analysis**: Run `doc-builder seo-check` to find and fix SEO issues
+- **Smart Defaults**: Intelligent fallbacks for missing SEO data
+
+### Configuration
+```javascript
+seo: {
+  titleTemplate: '{pageTitle} | {siteName}',
+  autoKeywords: true,
+  keywordLimit: 7,
+  descriptionFallback: 'smart'
+}
+```
+
 ## [1.5.4] - 2025-07-22
 
 ### Added

package/CLAUDE.md

@@ -312,6 +312,9 @@ build(config).then(() => {
 
 MIT License - See LICENSE file for details
 
+### NPM Features Documentation
+- When we add new features - add it to the NPM documented bullet point features - if its a big feature give it a section
+
 ---
 
 **Note**: This project was extracted from the cybersolstice monorepo on 2025-07-21 with full git history preservation.

package/README.md

@@ -49,6 +49,9 @@ This aligns perfectly with our mission: beautiful documentation should be access
 - 🔄 **Live Reload** - Development server with hot reloading
 - ☁️ **Vercel Integration** - One-command deployment to Vercel
 - 🔍 **SEO Optimized** - Meta tags, Open Graph, Twitter Cards, and structured data
+- ✅ **Google Site Verification** - Easy Google Search Console verification with CLI command
+- 📝 **Front Matter SEO** - Per-page titles, descriptions, and keywords with YAML front matter
+- 🎯 **SEO Analysis** - Built-in `seo-check` command to optimize your content
 - 📦 **Self-Contained** - No configuration or setup required
 - 🤖 **Claude Code Ready** - Optimized for AI-generated documentation workflows
 
@@ -147,6 +150,44 @@ npx @knowcode/doc-builder set-production-url https://my-custom-domain.com
 
 This is useful when you have a custom domain or Vercel alias that differs from the auto-detected URL.
 
+### google-verify
+
+Add Google site verification meta tag for Google Search Console:
+
+```bash
+# Add your verification code
+npx @knowcode/doc-builder google-verify YOUR_VERIFICATION_CODE
+
+# Example
+npx @knowcode/doc-builder google-verify FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ
+```
+
+This adds the verification meta tag to all generated HTML pages, allowing you to verify ownership in Google Search Console. See the [Google Site Verification Guide](docs/guides/google-site-verification-guide.md) for complete details.
+
+### seo-check
+
+Analyze and optimize your documentation's SEO:
+
+```bash
+# Check all pages for SEO issues
+npx @knowcode/doc-builder seo-check
+
+# Check a specific page
+npx @knowcode/doc-builder seo-check docs/guide.md
+
+# Future: Auto-fix common issues
+npx @knowcode/doc-builder seo-check --fix
+```
+
+This command analyzes:
+- Title length and optimization (50-60 characters)
+- Meta descriptions (140-160 characters)
+- Keywords usage and relevance
+- Front matter SEO fields
+- Content quality signals
+
+See the [SEO Optimization Guide](docs/guides/seo-optimization-guide.md) for best practices.
+
 ### setup-seo
 Interactive SEO configuration wizard:
 ```bash

package/cli.js

@@ -10,6 +10,7 @@ const { build } = require('./lib/builder');
 const { startDevServer } = require('./lib/dev-server');
 const { deployToVercel, setupVercelProject, prepareDeployment } = require('./lib/deploy');
 const { loadConfig, createDefaultConfig } = require('./lib/config');
+const { generateDescription } = require('./lib/seo');
 const { execSync } = require('child_process');
 
 // Package info
@@ -191,6 +192,177 @@ ${chalk.yellow('Get your verification code from Google Search Console.')}
     }
   });
 
+// SEO Check command
+program
+  .command('seo-check [path]')
+  .description('Analyze SEO for your documentation pages')
+  .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
+  .option('--fix', 'auto-fix common SEO issues')
+  .addHelpText('after', `
+${chalk.yellow('Examples:')}
+  ${chalk.gray('$')} doc-builder seo-check                    ${chalk.gray('# Check all pages')}
+  ${chalk.gray('$')} doc-builder seo-check docs/guide.md      ${chalk.gray('# Check specific page')}
+  ${chalk.gray('$')} doc-builder seo-check --fix              ${chalk.gray('# Auto-fix issues')}
+
+${chalk.yellow('This command analyzes:')}
+  • Title length and optimization (50-60 characters)
+  • Meta descriptions (140-160 characters)
+  • Keywords usage and relevance
+  • Front matter SEO fields
+  • Duplicate content issues
+`)
+  .action(async (filePath, options) => {
+    try {
+      const config = await loadConfig(options.config);
+      const docsDir = path.resolve(config.docsDir || 'docs');
+      
+      console.log(chalk.cyan('🔍 Analyzing SEO...'));
+      
+      // Get files to check
+      let files = [];
+      if (filePath) {
+        const fullPath = path.resolve(filePath);
+        if (await fs.pathExists(fullPath)) {
+          files = [fullPath];
+        } else {
+          console.error(chalk.red(`File not found: ${filePath}`));
+          process.exit(1);
+        }
+      } else {
+        // Get all markdown files
+        const getAllFiles = async (dir) => {
+          const results = [];
+          const items = await fs.readdir(dir);
+          for (const item of items) {
+            const fullPath = path.join(dir, item);
+            const stat = await fs.stat(fullPath);
+            if (stat.isDirectory() && !item.startsWith('.')) {
+              results.push(...await getAllFiles(fullPath));
+            } else if (item.endsWith('.md')) {
+              results.push(fullPath);
+            }
+          }
+          return results;
+        };
+        files = await getAllFiles(docsDir);
+      }
+      
+      // Analyze each file
+      const issues = [];
+      const suggestions = [];
+      
+      for (const file of files) {
+        const content = await fs.readFile(file, 'utf-8');
+        const { data: frontMatter, content: mainContent } = matter(content);
+        const relativePath = path.relative(docsDir, file);
+        
+        // Extract current metadata
+        const h1Match = mainContent.match(/^#\s+(.+)$/m);
+        const h1Title = h1Match ? h1Match[1] : null;
+        const title = frontMatter.title || h1Title || path.basename(file, '.md');
+        const description = frontMatter.description || generateDescription(mainContent, 'smart');
+        const keywords = frontMatter.keywords || [];
+        
+        // Check title
+        const titleLength = title.length;
+        if (titleLength > 60) {
+          issues.push({
+            file: relativePath,
+            type: 'title',
+            message: `Title too long (${titleLength} chars, max 60)`,
+            current: title,
+            suggestion: title.substring(0, 57) + '...'
+          });
+        } else if (titleLength < 30) {
+          suggestions.push({
+            file: relativePath,
+            type: 'title',
+            message: `Title might be too short (${titleLength} chars, ideal 50-60)`
+          });
+        }
+        
+        // Check description
+        const descLength = description.length;
+        if (descLength > 160) {
+          issues.push({
+            file: relativePath,
+            type: 'description',
+            message: `Description too long (${descLength} chars, max 160)`,
+            current: description,
+            suggestion: description.substring(0, 157) + '...'
+          });
+        } else if (descLength < 120) {
+          suggestions.push({
+            file: relativePath,
+            type: 'description',
+            message: `Description might be too short (${descLength} chars, ideal 140-160)`
+          });
+        }
+        
+        // Check keywords
+        if (keywords.length === 0 && !frontMatter.description) {
+          suggestions.push({
+            file: relativePath,
+            type: 'keywords',
+            message: 'No keywords defined in front matter'
+          });
+        }
+        
+        // Check for front matter
+        if (!frontMatter.title && !frontMatter.description) {
+          suggestions.push({
+            file: relativePath,
+            type: 'frontmatter',
+            message: 'No SEO front matter found'
+          });
+        }
+      }
+      
+      // Display results
+      console.log(`\n${chalk.cyan('📊 SEO Analysis Complete')}\n`);
+      console.log(`Analyzed ${files.length} files\n`);
+      
+      if (issues.length === 0 && suggestions.length === 0) {
+        console.log(chalk.green('✅ No SEO issues found!'));
+      } else {
+        if (issues.length > 0) {
+          console.log(chalk.red(`❌ Found ${issues.length} issues:\n`));
+          issues.forEach(issue => {
+            console.log(chalk.red(`  ${issue.file}:`));
+            console.log(chalk.yellow(`    ${issue.message}`));
+            if (issue.suggestion) {
+              console.log(chalk.gray(`    Suggestion: ${issue.suggestion.substring(0, 50)}...`));
+            }
+            console.log('');
+          });
+        }
+        
+        if (suggestions.length > 0) {
+          console.log(chalk.yellow(`💡 ${suggestions.length} suggestions:\n`));
+          suggestions.forEach(suggestion => {
+            console.log(chalk.yellow(`  ${suggestion.file}: ${suggestion.message}`));
+          });
+        }
+        
+        console.log(`\n${chalk.cyan('💡 Tips:')}`);
+        console.log('  • Add front matter to customize SEO per page');
+        console.log('  • Keep titles between 50-60 characters');
+        console.log('  • Write descriptions between 140-160 characters');
+        console.log('  • Include relevant keywords in front matter');
+        console.log(`\n${chalk.gray('Example front matter:')}`);
+        console.log(chalk.gray('---'));
+        console.log(chalk.gray('title: "Your SEO Optimized Title Here"'));
+        console.log(chalk.gray('description: "A compelling description between 140-160 characters that includes keywords and encourages clicks."'));
+        console.log(chalk.gray('keywords: ["keyword1", "keyword2", "keyword3"]'));
+        console.log(chalk.gray('---'));
+      }
+      
+    } catch (error) {
+      console.error(chalk.red('Failed to analyze SEO:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Set Production URL command
 program
   .command('set-production-url <url>')

package/html/README.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.764Z",
-  "dateModified": "2025-07-22T06:56:56.764Z",
+  "datePublished": "2025-07-22T07:02:21.490Z",
+  "dateModified": "2025-07-22T07:02:21.490Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/README.html"
@@ -95,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/documentation-index.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.775Z",
-  "dateModified": "2025-07-22T06:56:56.775Z",
+  "datePublished": "2025-07-22T07:02:21.500Z",
+  "dateModified": "2025-07-22T07:02:21.500Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/documentation-index.html"
@@ -95,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/guides/authentication-guide.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.778Z",
-  "dateModified": "2025-07-22T06:56:56.778Z",
+  "datePublished": "2025-07-22T07:02:21.503Z",
+  "dateModified": "2025-07-22T07:02:21.503Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/authentication-guide.html"
@@ -101,7 +101,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/guides/claude-workflow-guide.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.781Z",
-  "dateModified": "2025-07-22T06:56:56.781Z",
+  "datePublished": "2025-07-22T07:02:21.506Z",
+  "dateModified": "2025-07-22T07:02:21.506Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/claude-workflow-guide.html"
@@ -101,7 +101,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/guides/documentation-standards.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.784Z",
-  "dateModified": "2025-07-22T06:56:56.784Z",
+  "datePublished": "2025-07-22T07:02:21.509Z",
+  "dateModified": "2025-07-22T07:02:21.509Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/documentation-standards.html"
@@ -101,7 +101,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/guides/google-site-verification-guide.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.790Z",
-  "dateModified": "2025-07-22T06:56:56.790Z",
+  "datePublished": "2025-07-22T07:02:21.516Z",
+  "dateModified": "2025-07-22T07:02:21.516Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/google-site-verification-guide.html"
@@ -101,7 +101,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/guides/seo-guide.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.793Z",
-  "dateModified": "2025-07-22T06:56:56.793Z",
+  "datePublished": "2025-07-22T07:02:21.519Z",
+  "dateModified": "2025-07-22T07:02:21.519Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/seo-guide.html"
@@ -101,7 +101,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/guides/troubleshooting-guide.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.796Z",
-  "dateModified": "2025-07-22T06:56:56.796Z",
+  "datePublished": "2025-07-22T07:02:21.522Z",
+  "dateModified": "2025-07-22T07:02:21.522Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/guides/troubleshooting-guide.html"
@@ -101,7 +101,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/index.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.764Z",
-  "dateModified": "2025-07-22T06:56:56.764Z",
+  "datePublished": "2025-07-22T07:02:21.490Z",
+  "dateModified": "2025-07-22T07:02:21.490Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/README.html"
@@ -95,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/html/sitemap.xml

@@ -2,85 +2,85 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://doc-builder-delta.vercel.app/404.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/README.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/claude-workflow-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/documentation-index.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/authentication-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/claude-workflow-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/document-standards.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/documentation-standards.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/google-site-verification-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/seo-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/guides/troubleshooting-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/index.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/vercel-cli-setup-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html</loc>
-    <lastmod>2025-07-22T06:56:56.811Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>

package/html/vercel-cli-setup-guide.html

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.800Z",
-  "dateModified": "2025-07-22T06:56:56.800Z",
+  "datePublished": "2025-07-22T07:02:21.526Z",
+  "dateModified": "2025-07-22T07:02:21.526Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/vercel-cli-setup-guide.html"
@@ -95,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

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

@@ -61,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:56:56.803Z",
-  "dateModified": "2025-07-22T06:56:56.803Z",
+  "datePublished": "2025-07-22T07:02:21.530Z",
+  "dateModified": "2025-07-22T07:02:21.530Z",
   "mainEntityOfPage": {
     "@type": "WebPage",
     "@id": "https://doc-builder-delta.vercel.app/vercel-first-time-setup-guide.html"
@@ -95,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.3">Last updated: Jul 22, 2025, 06:56 AM UTC</span>
+                    <span class="deployment-date" title="Built with doc-builder v1.5.4">Last updated: Jul 22, 2025, 07:02 AM UTC</span>
                 </div>
                 
                 

package/lib/config.js

@@ -55,6 +55,10 @@ const defaultConfig = {
     twitterHandle: '',
     language: 'en-US',
     keywords: [],
+    titleTemplate: '{pageTitle} | {siteName}',  // Customizable title format
+    autoKeywords: true,  // Extract keywords from content
+    keywordLimit: 7,  // Max keywords per page
+    descriptionFallback: 'smart',  // 'smart' or 'first-paragraph'
     organization: {
       name: '',
       url: '',

package/lib/core-builder.js

@@ -2,6 +2,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const marked = require('marked');
 const chalk = require('chalk');
+const matter = require('gray-matter');
 const { 
   generateMetaTags, 
   generateJSONLD, 
@@ -189,7 +190,7 @@ function processMarkdownContent(content) {
 }
 
 // Generate HTML from template
-function generateHTML(title, content, navigation, currentPath = '', config = {}, originalContent = '') {
+function generateHTML(title, content, navigation, currentPath = '', config = {}, originalContent = '', frontMatter = {}) {
   const depth = currentPath.split('/').filter(p => p).length;
   const relativePath = depth > 0 ? '../'.repeat(depth) : '';
   
@@ -203,24 +204,40 @@ function generateHTML(title, content, navigation, currentPath = '', config = {},
   // SEO preparation
   let seoTags = '';
   let jsonLd = '';
+  let finalSeoTitle = `${title} - ${siteName}`;
+  let pageDescription = frontMatter.description || 
+                       generateDescription(originalContent || content, config.seo?.descriptionFallback) || 
+                       siteDescription;
   
   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])];
+    // Extract keywords - priority: front matter > content extraction + global
+    const contentKeywords = config.seo?.autoKeywords !== false ? 
+                          extractKeywords(originalContent || content, config.seo?.keywordLimit || 7) : 
+                          [];
+    const pageKeywords = frontMatter.keywords || [];
+    const keywords = [...new Set([...(config.seo.keywords || []), ...pageKeywords, ...contentKeywords])]
+                     .slice(0, config.seo?.keywordLimit || 7);
     
     // Generate breadcrumbs
     const breadcrumbs = generateBreadcrumbs(currentPath, config.seo.siteUrl, siteName);
     
+    // Generate SEO-optimized title
+    const titleTemplate = config.seo?.titleTemplate || '{pageTitle} | {siteName}';
+    const seoTitle = titleTemplate
+      .replace('{pageTitle}', title)
+      .replace('{siteName}', siteName);
+    
+    // Ensure title is within 50-60 characters
+    finalSeoTitle = seoTitle.length > 60 ? 
+      title.length > 50 ? title.substring(0, 50) + '...' : title 
+      : seoTitle;
+    
     // Generate meta tags
     seoTags = generateMetaTags({
-      title: `${title} - ${siteName}`,
+      title: finalSeoTitle,
       description: pageDescription,
       url: pageUrl,
       author: config.seo.author,
@@ -254,8 +271,8 @@ function generateHTML(title, content, navigation, currentPath = '', config = {},
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="description" content="${escapeHtml(generateDescription(originalContent || content) || siteDescription)}">
-    <title>${escapeHtml(title)} - ${escapeHtml(siteName)}</title>
+    <meta name="description" content="${escapeHtml(pageDescription || generateDescription(originalContent || content) || siteDescription)}">
+    <title>${escapeHtml(finalSeoTitle || `${title} - ${siteName}`)}</title>
     
 ${seoTags}
     
@@ -578,17 +595,21 @@ function buildNavigationStructure(files, currentFile) {
 
 // Process single markdown file
 async function processMarkdownFile(filePath, outputPath, allFiles, config) {
-  const content = await fs.readFile(filePath, 'utf-8');
+  const rawContent = await fs.readFile(filePath, 'utf-8');
   const fileName = path.basename(filePath, '.md');
   const relativePath = path.relative(config.docsDir, filePath);
   const urlPath = relativePath.replace(/\.md$/, '.html').replace(/\\/g, '/');
   
-  // Extract title from content
-  const titleMatch = content.match(/^#\s+(.+)$/m);
-  const title = titleMatch ? titleMatch[1] : fileName;
+  // Parse front matter
+  const { data: frontMatter, content } = matter(rawContent);
+  
+  // Extract title - priority: front matter > H1 > filename
+  const h1Match = content.match(/^#\s+(.+)$/m);
+  const h1Title = h1Match ? h1Match[1] : null;
+  const title = frontMatter.title || h1Title || fileName;
   
-  // Extract summary for tooltip
-  const summary = extractSummary(content);
+  // Extract summary for tooltip - priority: front matter > auto-extract
+  const summary = frontMatter.description || extractSummary(content);
   
   // Process content
   const htmlContent = processMarkdownContent(content);
@@ -596,14 +617,14 @@ async function processMarkdownFile(filePath, outputPath, allFiles, config) {
   // Build navigation
   const navigation = buildNavigationStructure(allFiles, urlPath);
   
-  // Generate full HTML (pass original content for SEO)
-  const html = generateHTML(title, htmlContent, navigation, urlPath, config, content);
+  // Generate full HTML (pass original content and front matter for SEO)
+  const html = generateHTML(title, htmlContent, navigation, urlPath, config, content, frontMatter);
   
   // Write file
   await fs.ensureDir(path.dirname(outputPath));
   await fs.writeFile(outputPath, html);
   
-  return { title, urlPath, summary };
+  return { title, urlPath, summary, frontMatter };
 }
 
 // Get all markdown files

package/lib/seo.js

@@ -48,23 +48,60 @@ function extractKeywords(content, maxKeywords = 10) {
 /**
  * Generate meta description from content
  */
-function generateDescription(content, maxLength = 160) {
-  // Remove markdown syntax and get first paragraph
+function generateDescription(content, mode = 'smart', maxLength = 160) {
+  // Remove markdown syntax
   const plainText = content
     .replace(/```[\s\S]*?```/g, '') // Remove code blocks
+    .replace(/^---[\s\S]*?---/m, '') // Remove front matter
     .replace(/#+\s(.+)/g, '$1. ') // Convert headers to sentences
     .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // Extract link text
     .replace(/[*_~]/g, '') // Remove emphasis
     .replace(/\n+/g, ' ') // Replace newlines with spaces
     .trim();
   
-  // Find first sentence or use first maxLength characters
-  const firstSentence = plainText.match(/^[^.!?]+[.!?]/);
-  let description = firstSentence ? firstSentence[0] : plainText;
+  let description = '';
+  
+  if (mode === 'smart') {
+    // Try to find intro paragraph after first header
+    const lines = content.split('\n');
+    let foundH1 = false;
+    let introText = '';
+    
+    for (const line of lines) {
+      if (line.match(/^#\s+/)) {
+        foundH1 = true;
+        continue;
+      }
+      if (foundH1 && line.trim() && !line.match(/^#/)) {
+        introText = line.trim();
+        break;
+      }
+    }
+    
+    if (introText) {
+      // Clean markdown from intro text
+      description = introText
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+        .replace(/[*_~]/g, '');
+    }
+  }
+  
+  // Fallback to first paragraph
+  if (!description) {
+    const firstSentence = plainText.match(/^[^.!?]+[.!?]/);
+    description = firstSentence ? firstSentence[0] : plainText;
+  }
   
-  // Truncate if needed
+  // Ensure optimal length (140-160 chars)
   if (description.length > maxLength) {
-    description = description.substring(0, maxLength - 3) + '...';
+    // Try to cut at word boundary
+    const cutPoint = description.lastIndexOf(' ', maxLength - 3);
+    description = description.substring(0, cutPoint > 100 ? cutPoint : maxLength - 3) + '...';
+  } else if (description.length < 140 && description.length > 100) {
+    // Maybe add a call to action if too short
+    if (!description.match(/[.!?]$/)) {
+      description += '.';
+    }
   }
   
   return description;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {
@@ -27,6 +27,7 @@
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
     "fs-extra": "^11.2.0",
+    "gray-matter": "^4.0.3",
     "marked": "^15.0.12",
     "ora": "5.4.1",
     "prompts": "^2.4.2"