@mgks/docmd 0.1.0

package/src/plugins/seo.js

@@ -0,0 +1,65 @@
+// src/plugins/seo.js
+function generateSeoMetaTags(config, pageData, relativePathToRoot) {
+    let metaTagsHtml = '';
+    const { frontmatter, outputPath } = pageData;
+  
+    if (frontmatter.noindex) {
+      metaTagsHtml += '  <meta name="robots" content="noindex">\n';
+      return metaTagsHtml; // No other SEO tags if noindex
+    }
+  
+    const siteTitle = config.siteTitle;
+    const pageTitle = frontmatter.title || 'Untitled'; // Ensure pageTitle is always defined
+    const description = frontmatter.description || config.plugins?.seo?.defaultDescription || '';
+  
+    // Construct pageUrl - ensure siteUrl in config has no trailing slash
+    const siteUrl = config.siteUrl ? config.siteUrl.replace(/\/$/, '') : '';
+    const pageSegment = outputPath.replace(/index\.html$/, '').replace(/\.html$/, '');
+    const pageUrl = `${siteUrl}${pageSegment.startsWith('/') ? pageSegment : '/' + pageSegment}`;
+  
+    metaTagsHtml += `  <meta name="description" content="${description}">\n`;
+  
+    // Open Graph
+    metaTagsHtml += `  <meta property="og:title" content="${pageTitle} | ${siteTitle}">\n`;
+    metaTagsHtml += `  <meta property="og:description" content="${description}">\n`;
+    metaTagsHtml += `  <meta property="og:url" content="${pageUrl}">\n`;
+    metaTagsHtml += `  <meta property="og:site_name" content="${config.plugins?.seo?.openGraph?.siteName || siteTitle}">\n`;
+  
+    const ogImage = frontmatter.image || frontmatter.ogImage || config.plugins?.seo?.openGraph?.defaultImage;
+    if (ogImage) {
+      const ogImageUrl = ogImage.startsWith('http') ? ogImage : `${siteUrl}${ogImage.startsWith('/') ? ogImage : '/' + ogImage}`;
+      metaTagsHtml += `  <meta property="og:image" content="${ogImageUrl}">\n`;
+    }
+    metaTagsHtml += `  <meta property="og:type" content="${frontmatter.ogType || 'website'}">\n`;
+  
+    // Twitter Card
+    const twitterCardType = frontmatter.twitterCard || config.plugins?.seo?.twitter?.cardType || 'summary';
+    metaTagsHtml += `  <meta name="twitter:card" content="${twitterCardType}">\n`;
+    if (config.plugins?.seo?.twitter?.siteUsername) {
+      metaTagsHtml += `  <meta name="twitter:site" content="${config.plugins.seo.twitter.siteUsername}">\n`;
+    }
+    const twitterCreator = frontmatter.twitterCreator || config.plugins?.seo?.twitter?.creatorUsername;
+    if (twitterCreator) {
+      metaTagsHtml += `  <meta name="twitter:creator" content="${twitterCreator}">\n`;
+    }
+    // Twitter title, description, image often fallback to OG tags if not explicitly set by Twitter.
+    // For explicitness:
+    metaTagsHtml += `  <meta name="twitter:title" content="${pageTitle} | ${siteTitle}">\n`;
+    metaTagsHtml += `  <meta name="twitter:description" content="${description}">\n`;
+    if (ogImage) { // Re-use ogImage for twitter:image if not specified differently
+      const twitterImageUrl = ogImage.startsWith('http') ? ogImage : `${siteUrl}${ogImage.startsWith('/') ? ogImage : '/' + ogImage}`;
+      metaTagsHtml += `  <meta name="twitter:image" content="${twitterImageUrl}">\n`;
+    }
+  
+  
+    // Keywords (optional, less impact nowadays)
+    if (frontmatter.keywords) {
+      const keywordsString = Array.isArray(frontmatter.keywords) ? frontmatter.keywords.join(', ') : frontmatter.keywords;
+      metaTagsHtml += `  <meta name="keywords" content="${keywordsString}">\n`;
+    }
+  
+  
+    return metaTagsHtml;
+  }
+  
+  module.exports = { generateSeoMetaTags };

package/src/plugins/sitemap.js

@@ -0,0 +1,100 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Generate sitemap.xml in the output directory root
+ * @param {Object} config - The full configuration object
+ * @param {Array} pages - Array of page objects with data about each processed page
+ * @param {string} outputDir - Path to the output directory
+ */
+async function generateSitemap(config, pages, outputDir) {
+  // Skip if no siteUrl is defined (sitemap needs absolute URLs)
+  if (!config.siteUrl) {
+    console.warn('⚠️ No siteUrl defined in config. Skipping sitemap generation.');
+    return;
+  }
+
+  // Normalize siteUrl to ensure it has no trailing slash
+  const siteUrl = config.siteUrl.replace(/\/$/, '');
+  
+  // Sitemap XML header
+  let sitemapXml = '<?xml version="1.0" encoding="UTF-8"?>\n';
+  sitemapXml += '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n';
+  
+  // Get default settings from config
+  const defaultChangefreq = config.plugins?.sitemap?.defaultChangefreq || 'weekly';
+  const defaultPriority = config.plugins?.sitemap?.defaultPriority || 0.8;
+
+  const rootPriority = config.plugins?.sitemap?.rootPriority || 1.0;
+
+  // Helper function to convert paths to URLs
+  function pathToUrl(pagePath) {
+    // Handle index.html
+    if (pagePath === 'index.html') {
+      return siteUrl + '/';
+    }
+    
+    // For paths already using pretty URLs (ending with slash)
+    if (pagePath.endsWith('/')) {
+      return siteUrl + '/' + pagePath;
+    }
+    
+    // For paths still using .html extension
+    // Convert to no-extension format
+    if (pagePath.endsWith('.html')) {
+      const pathWithoutExt = pagePath.substring(0, pagePath.length - 5);
+      if (pathWithoutExt === '') {
+        return siteUrl + '/';
+      } else {
+        return siteUrl + '/' + pathWithoutExt + '/';
+      }
+    }
+    
+    // Default case
+    return siteUrl + '/' + pagePath;
+  }
+
+  for (const page of pages) {
+    // Parse frontmatter for sitemap-specific overrides and metadata
+    const frontmatter = page.frontmatter || {};
+    const pagePath = page.outputPath || '';
+    
+    // Skip if page is explicitly excluded from sitemap
+    if (frontmatter.sitemap === false) {
+      continue;
+    }
+
+    // Determine URL for this page
+    let url = pathToUrl(pagePath);
+
+    // Set priority
+    let priority = frontmatter.priority || 
+                   (pagePath === 'index.html' ? rootPriority : defaultPriority);
+    
+    // Set change frequency
+    const changefreq = frontmatter.changefreq || defaultChangefreq;
+    
+    // Add page to sitemap
+    sitemapXml += '  <url>\n';
+    sitemapXml += `    <loc>${url}</loc>\n`;
+    
+    // Add lastmod if available in frontmatter
+    if (frontmatter.lastmod) {
+      sitemapXml += `    <lastmod>${frontmatter.lastmod}</lastmod>\n`;
+    }
+    
+    sitemapXml += `    <changefreq>${changefreq}</changefreq>\n`;
+    sitemapXml += `    <priority>${priority}</priority>\n`;
+    sitemapXml += '  </url>\n';
+  }
+  
+  sitemapXml += '</urlset>';
+  
+  // Write sitemap file
+  const sitemapPath = path.join(outputDir, 'sitemap.xml');
+  await fs.writeFile(sitemapPath, sitemapXml);
+  
+  console.log(`✅ Generated sitemap at ${sitemapPath}`);
+}
+
+module.exports = { generateSitemap }; 

package/src/templates/layout.ejs

@@ -0,0 +1,174 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+    <%- metaTagsHtml || '' %> <%# SEO Plugin Meta Tags %>
+
+    <title><%= pageTitle %> | <%= siteTitle %></title>
+    <% if (description && !(metaTagsHtml && metaTagsHtml.includes('name="description"'))) { %>
+      <meta name="description" content="<%= description %>">
+    <% } %>
+
+    <%- faviconLinkHtml || '' %> <%# Favicon %>
+
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/main.css">
+
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/highlight-<%= defaultMode === 'dark' ? 'dark' : 'light' %>.css" id="highlight-theme">
+
+    <%- themeCssLinkHtml || '' %> <%# For theme.name specific CSS %>
+
+    <% (customCssFiles || []).forEach(cssFile => { %>
+      <link rel="stylesheet" href="<%= relativePathToRoot %><%- cssFile.startsWith('/') ? cssFile.substring(1) : cssFile %>">
+    <% }); %>
+
+    <%- pluginStylesHtml || '' %> <%# Plugin specific CSS %>
+
+    <%- pluginHeadScriptsHtml || '' %> <%# Plugin specific head scripts (e.g., Analytics) %>
+</head>
+<body data-theme="<%= defaultMode %>">
+    <aside class="sidebar">
+        <div class="sidebar-header">
+            <% if (logo && logo.light && logo.dark) { %>
+                <a href="<%= logo.href || (relativePathToRoot + 'index.html') %>" class="logo-link">
+                    <img src="<%= relativePathToRoot %><%- logo.light.startsWith('/') ? logo.light.substring(1) : logo.light %>" alt="<%= logo.alt || siteTitle %>" class="logo-light" <% if (logo.height) { %>style="height: <%= logo.height %>;"<% } %>>
+                    <img src="<%= relativePathToRoot %><%- logo.dark.startsWith('/') ? logo.dark.substring(1) : logo.dark %>" alt="<%= logo.alt || siteTitle %>" class="logo-dark" <% if (logo.height) { %>style="height: <%= logo.height %>;"<% } %>>
+                </a>
+            <% } else { %>
+                <h1><a href="<%= relativePathToRoot %>index.html"><%= siteTitle %></a></h1>
+            <% } %>
+        </div>
+        <%- navigationHtml %>
+        <% if (theme && theme.enableModeToggle) { %>
+          <button id="theme-toggle-button" aria-label="Toggle theme" class="theme-toggle-button">
+            <%# renderIcon is available in the global EJS scope from html-generator %>
+            <%- renderIcon('sun', { class: 'icon-sun' }) %>
+            <%- renderIcon('moon', { class: 'icon-moon' }) %>
+          </button>
+        <% } %>
+    </aside>
+    <div class="main-content-wrapper">
+        <header class="page-header">
+            <h1><%= pageTitle %></h1>
+        </header>
+        <main class="content-area">
+            <div class="content-layout">
+                <div class="main-content">
+                    <%- content %>
+                    
+                    <% if (prevPage || nextPage) { %>
+                    <div class="page-navigation">
+                        <% if (prevPage) { %>
+                        <a href="<%= prevPage.url %>" class="prev-page">
+                            <%- renderIcon('arrow-left', { class: 'page-nav-icon' }) %>
+                            <span>
+                                <small>Previous</small>
+                                <strong><%= prevPage.title %></strong>
+                            </span>
+                        </a>
+                        <% } else { %>
+                        <div class="prev-page-placeholder"></div>
+                        <% } %>
+                        
+                        <% if (nextPage) { %>
+                        <a href="<%= nextPage.url %>" class="next-page">
+                            <span>
+                                <small>Next</small>
+                                <strong><%= nextPage.title %></strong>
+                            </span>
+                            <%- renderIcon('arrow-right', { class: 'page-nav-icon' }) %>
+                        </a>
+                        <% } else { %>
+                        <div class="next-page-placeholder"></div>
+                        <% } %>
+                    </div>
+                    <% } %>
+                </div>
+                
+                <!-- DEBUG: <%- JSON.stringify({headingsLength: headings ? headings.length : 0}) %> -->
+                
+                <!-- TOC sidebar -->
+                <div class="toc-sidebar">
+                    <% 
+                    // Helper function to decode HTML entities
+                    function decodeHtmlEntities(html) {
+                      return html
+                        .replace(/&amp;/g, '&')
+                        .replace(/&lt;/g, '<')
+                        .replace(/&gt;/g, '>')
+                        .replace(/&quot;/g, '"')
+                        .replace(/&#39;/g, "'")
+                        .replace(/&nbsp;/g, ' ');
+                    }
+                    
+                    // Only show TOC on active pages
+                    const isActive = navigationHtml && navigationHtml.includes('class="active"');
+                    
+                    if (isActive) {
+                      // Extract headings directly from content - match with or without id attribute
+                      const headingRegex = /<h([2-4])[^>]*?(?:id="([^"]*)")?[^>]*?>([\s\S]*?)<\/h\1>/g;
+                      const tocHeadings = [];
+                      let match;
+                      let contentStr = content.toString();
+
+                      while ((match = headingRegex.exec(contentStr)) !== null) {
+                          const level = parseInt(match[1], 10);
+                          // Use ID if available, or generate one from the text
+                          let id = match[2];
+                          // Remove any HTML tags inside the heading text and decode HTML entities
+                          const textWithTags = match[3].replace(/<\/?[^>]+(>|$)/g, '');
+                          // Decode HTML entities
+                          const text = decodeHtmlEntities(textWithTags);
+                          
+                          if (!id) {
+                              // Generate an ID from the heading text if none exists
+                              id = text
+                                .toLowerCase()
+                                .replace(/\s+/g, '-')
+                                .replace(/[^\w-]/g, '')
+                                .replace(/--+/g, '-')
+                                .replace(/^-+|-+$/g, '');
+                          }
+                          
+                          tocHeadings.push({ id, level, text });
+                      }
+                      
+                      // Only show TOC if there are enough headings
+                      if (tocHeadings.length > 1) { 
+                      %>
+                          <div class="toc-container">
+                              <h2 class="toc-title">On This Page</h2>
+                              <ul class="toc-list">
+                                  <% tocHeadings.forEach(heading => { %>
+                                      <li class="toc-item toc-level-<%= heading.level %>">
+                                          <a href="#<%= heading.id %>" class="toc-link"><%- heading.text %></a>
+                                      </li>
+                                  <% }); %>
+                              </ul>
+                          </div>
+                      <% } 
+                    } %>
+                </div>
+            </div>
+        </main>
+        <footer class="page-footer">
+            <div class="footer-content">
+                <div class="user-footer">
+                    <%- footerHtml || '' %>
+                </div>
+                <div class="branding-footer">
+                    Build with 💜 <a href="https://docmd.mgks.dev" target="_blank" rel="noopener">docmd.</a>
+                </div>
+            </div>
+        </footer>
+    </div>
+
+    <script src="<%= relativePathToRoot %>assets/js/theme-toggle.js"></script>
+    <% (customJsFiles || []).forEach(jsFile => { %>
+      <script src="<%= relativePathToRoot %><%- jsFile.startsWith('/') ? jsFile.substring(1) : jsFile %>"></script>
+    <% }); %>
+
+    <%- pluginBodyScriptsHtml || '' %> <%# Plugin specific body scripts %>
+</body>
+</html>

package/src/templates/navigation.ejs

@@ -0,0 +1,107 @@
+<%# src/templates/navigation.ejs %>
+
+<%# renderIcon is passed from html-generator.js %>
+
+<% 
+// Debug function - uncomment to troubleshoot paths
+function debugNavPaths(item, itemPath, currentPath, isActive, isParentActive) {
+  console.log('\nDEBUG NAV ITEM:');
+  console.log(`Title: ${item.title}`);
+  console.log(`Path: ${item.path}`);
+  console.log(`Computed item path: ${itemPath}`);
+  console.log(`Current page path: ${currentPath}`);
+  console.log(`Is directly active: ${isActive}`);
+  console.log(`Is parent active: ${isParentActive}`);
+}
+
+function renderNavItems(items, currentLevelPagePath, rootPath) { %>
+  <ul>
+    <% items.forEach(item => { %>
+      <%
+        let itemHref = '#'; // Default for non-linking parents or error
+        let isCurrentPageActive = false;
+        let isActivePage = false; // For the direct page itself
+        const isExternal = item.external === true;
+        const targetBlank = isExternal ? 'target="_blank" rel="noopener noreferrer"' : '';
+        let iconHtml = '';
+        let externalLinkIconHtml = '';
+
+        if (item.icon) {
+          // Use custom class for nav icons for specific styling
+          iconHtml = renderIcon(item.icon, { class: 'nav-item-icon' });
+        }
+
+        if (isExternal) {
+          itemHref = item.path; // Full URL for external links
+          // Use a Lucide icon like 'arrow-up-right' or 'external-link'
+          externalLinkIconHtml = renderIcon('arrow-up-right', { class: 'nav-external-icon', width: '0.8em', height: '0.8em' });
+        } else {
+          // Path normalization for internal links
+          let cleanPath = item.path.startsWith('/') ? item.path : '/' + item.path; // Ensure leading slash
+
+          // Handle paths with pretty URLs
+          if (cleanPath === '/') {
+            // Root path goes to index.html
+            itemHref = rootPath + 'index.html';
+          } else {
+            // Remove any trailing slash for consistency
+            const pathWithoutTrailingSlash = cleanPath.endsWith('/') ? cleanPath.slice(0, -1) : cleanPath;
+            
+            // For all other paths, link to the directory (pretty URL)
+            // Remove leading slash and ensure clean path
+            const cleanedPath = pathWithoutTrailingSlash.substring(1);
+            itemHref = rootPath + cleanedPath + '/';
+          }
+
+          // SIMPLIFIED ACTIVE STATE LOGIC - START
+          // 1. Prepare the paths for comparison
+          // The item path in the format used in the navigation config
+          const normalizedItemPath = cleanPath.substring(1) || '';
+          
+          // Special handling for root path
+          if (cleanPath === '/') {
+            isActivePage = currentLevelPagePath === 'index.html';
+            isCurrentPageActive = isActivePage;
+          } 
+          // Parent folder with index.md
+          else if (cleanPath.endsWith('/')) {
+            // Direct match for folder/index.html pages
+            const folderPath = cleanPath.substring(1, cleanPath.length - 1); // Remove leading / and trailing /
+            isActivePage = currentLevelPagePath === folderPath + '/';
+            isCurrentPageActive = isActivePage;
+            
+            // Check if any children are active 
+            // If current path starts with this item's path, it's a parent of the active page
+            if (!isActivePage && currentLevelPagePath.startsWith(normalizedItemPath)) {
+              isCurrentPageActive = true;
+            }
+          } 
+          // Regular page
+          else {
+            const pagePath = cleanPath.substring(1) + '/';
+            isActivePage = currentLevelPagePath === pagePath;
+            isCurrentPageActive = isActivePage;
+          }
+          // SIMPLIFIED ACTIVE STATE LOGIC - END
+        }
+      %>
+      <li class="<%= isCurrentPageActive ? 'active-parent' : '' %>">
+        <a href="<%= itemHref %>"
+           class="<%= isActivePage ? 'active' : '' %>"
+           <%- targetBlank %>>
+          <% if (iconHtml) { %><%- iconHtml %><% } %>
+          <span><%- item.title %></span> <%# Wrap title in span for styling if needed %>
+          <% if (externalLinkIconHtml) { %><%- externalLinkIconHtml %><% } %>
+        </a>
+
+        <% if (item.children && item.children.length > 0) { %>
+          <%- renderNavItems(item.children, currentLevelPagePath, rootPath) %>
+        <% } %>
+      </li>
+    <% }); %>
+  </ul>
+<% } %>
+
+<nav class="sidebar-nav">
+  <%- renderNavItems(navItems, currentPagePath, relativePathToRoot) %>
+</nav>

package/src/templates/toc.ejs

@@ -0,0 +1,34 @@
+<%# src/templates/toc.ejs %>
+<% 
+// If direct headings aren't available, we'll try to extract them from the content
+let tocHeadings = [];
+if (headings && headings.length > 0) {
+  // Use provided headings if available
+  tocHeadings = headings.filter(h => h.level >= 2 && h.level <= 4);
+} else if (content) {
+  // Basic regex to extract headings from HTML content
+  const headingRegex = /<h([2-4])[^>]*?id="([^"]*)"[^>]*?>([\s\S]*?)<\/h\1>/g;
+  let match;
+  while ((match = headingRegex.exec(content)) !== null) {
+    const level = parseInt(match[1], 10);
+    const id = match[2];
+    // Remove any HTML tags inside the heading text
+    const text = match[3].replace(/<\/?[^>]+(>|$)/g, '');
+    tocHeadings.push({ id, level, text });
+  }
+}
+
+// Only show TOC if there are enough headings
+if (tocHeadings.length > 1) { 
+%>
+  <div class="toc-container">
+    <h2 class="toc-title">On This Page</h2>
+    <ul class="toc-list">
+      <% tocHeadings.forEach(heading => { %>
+        <li class="toc-item toc-level-<%= heading.level %>">
+          <a href="#<%= heading.id %>" class="toc-link"><%= heading.text %></a>
+        </li>
+      <% }); %>
+    </ul>
+  </div>
+<% } %>