@knowcode/doc-builder 1.5.3 → 1.5.5

package/html/sitemap.xml

@@ -2,79 +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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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-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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</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:01:14.316Z</lastmod>
+    <lastmod>2025-07-22T07:02:21.540Z</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.8</priority>
   </url>

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

@@ -28,6 +28,9 @@
     <meta name="twitter:description" content="Vercel CLI Setup Guide.">
     <meta name="twitter:image" content="https://doc-builder-delta.vercel.app/og-default.png">
     
+    <!-- Custom Meta Tags -->
+    <meta name="google-site-verification" content="FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ">
+    
     <!-- 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">
     
@@ -58,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:01:14.298Z",
-  "dateModified": "2025-07-22T06:01:14.298Z",
+  "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"
@@ -92,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.2">Last updated: Jul 22, 2025, 06:01 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>
                 
                 
@@ -153,6 +156,7 @@
         <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/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="/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/google-site-verification-guide.html" class="nav-item" data-tooltip="Google Search Console verification allows you to: Monitor your site&#039;s performance in Google Search Submit sitemaps for better indexing View search..."><i class="fas fa-file-alt"></i> Google Site Verification Guide</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>

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

@@ -28,6 +28,9 @@
     <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">
     
+    <!-- Custom Meta Tags -->
+    <meta name="google-site-verification" content="FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ">
+    
     <!-- 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">
     
@@ -58,8 +61,8 @@
     "name": "Knowcode Ltd",
     "url": "https://knowcode.tech"
   },
-  "datePublished": "2025-07-22T06:01:14.306Z",
-  "dateModified": "2025-07-22T06:01:14.306Z",
+  "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"
@@ -92,7 +95,7 @@
             
             <div class="header-actions">
                 <div class="deployment-info">
-                    <span class="deployment-date" title="Built with doc-builder v1.5.2">Last updated: Jul 22, 2025, 06:01 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>
                 
                 
@@ -153,6 +156,7 @@
         <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/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="/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/google-site-verification-guide.html" class="nav-item" data-tooltip="Google Search Console verification allows you to: Monitor your site&#039;s performance in Google Search Submit sitemaps for better indexing View search..."><i class="fas fa-file-alt"></i> Google Site Verification Guide</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>

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,
@@ -229,7 +246,8 @@ function generateHTML(title, content, navigation, currentPath = '', config = {},
       ogImage: config.seo.ogImage,
       siteName: siteName,
       language: config.seo.language,
-      type: 'article'
+      type: 'article',
+      customMetaTags: config.seo.customMetaTags || []
     });
     
     // Generate JSON-LD
@@ -253,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}
     
@@ -577,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);
@@ -595,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, '');
+    }
+  }
   
-  // Truncate if needed
+  // Fallback to first paragraph
+  if (!description) {
+    const firstSentence = plainText.match(/^[^.!?]+[.!?]/);
+    description = firstSentence ? firstSentence[0] : plainText;
+  }
+  
+  // 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;
@@ -84,7 +121,8 @@ function generateMetaTags(options) {
     ogImage,
     siteName,
     language = 'en-US',
-    type = 'article'
+    type = 'article',
+    customMetaTags = []
   } = options;
   
   const tags = [];
@@ -157,6 +195,18 @@ function generateMetaTags(options) {
     }
   }
   
+  // Add custom meta tags
+  if (customMetaTags && customMetaTags.length > 0) {
+    tags.push(`    \n    <!-- Custom Meta Tags -->`);
+    customMetaTags.forEach(tag => {
+      if (tag.name && tag.content) {
+        tags.push(`    <meta name="${escapeHtml(tag.name)}" content="${escapeHtml(tag.content)}">`);
+      } else if (tag.property && tag.content) {
+        tags.push(`    <meta property="${escapeHtml(tag.property)}" content="${escapeHtml(tag.content)}">`);
+      }
+    });
+  }
+  
   return tags.join('\n');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.5.3",
+  "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"