@mgks/docmd 0.1.0 → 0.1.1

package/src/commands/dev.js

@@ -8,7 +8,7 @@ const fs = require('fs-extra');
 const { buildSite } = require('./build'); // Re-use the build logic
 const { loadConfig } = require('../core/config-loader');
 
-async function startDevServer(configPathOption) {
+async function startDevServer(configPathOption, options = { preserve: false }) {
   let config = await loadConfig(configPathOption); // Load initial config
   const CWD = process.cwd(); // Current Working Directory where user runs `docmd dev`
 
@@ -88,7 +88,7 @@ async function startDevServer(configPathOption) {
   // Initial build
   console.log('🚀 Performing initial build for dev server...');
   try {
-    await buildSite(configPathOption, { isDev: true }); // Use the original config path option
+    await buildSite(configPathOption, { isDev: true, preserve: options.preserve }); // Use the original config path option
     console.log('✅ Initial build complete.');
   } catch (error) {
       console.error('❌ Initial build failed:', error.message, error.stack);
@@ -143,7 +143,7 @@ async function startDevServer(configPathOption) {
         paths = newPaths; // Update paths for next build reference
       }
 
-      await buildSite(configPathOption, { isDev: true }); // Re-build using the potentially updated config path
+      await buildSite(configPathOption, { isDev: true, preserve: options.preserve }); // Re-build using the potentially updated config path
       broadcastReload();
       console.log('✅ Rebuild complete. Browser should refresh.');
     } catch (error) {

package/src/commands/init.js

@@ -1,23 +1,93 @@
 const fs = require('fs-extra');
 const path = require('path');
 
-const defaultConfigContent = `// config.js
+const defaultConfigContent = `// config.js: basic config for docmd
 module.exports = {
-  siteTitle: 'My Awesome Project Docs',
-  srcDir: 'docs',
-  outputDir: 'site',
+  // Core Site Metadata
+  siteTitle: 'docmd',
+  // Define a base URL for your site, crucial for SEO and absolute paths
+  // No trailing slash
+  siteUrl: '', // Replace with your actual deployed URL
+
+  // Logo Configuration
+  logo: {
+    light: '/assets/images/docmd-logo-light.png', // Path relative to outputDir root
+    dark: '/assets/images/docmd-logo-dark.png',   // Path relative to outputDir root
+    alt: 'docmd logo',                      // Alt text for the logo
+    href: '/',                              // Link for the logo, defaults to site root
+  },
+
+  // Directory Configuration
+  srcDir: 'docs',       // Source directory for Markdown files
+  outputDir: 'site',    // Directory for generated static site
+
+  // Theme Configuration
   theme: {
-    defaultMode: 'light', // 'light' or 'dark'
+    name: 'sky',            // Themes: 'default', 'sky'
+    defaultMode: 'light',   // Initial color mode: 'light' or 'dark'
+    enableModeToggle: true, // Show UI button to toggle light/dark modes
+    customCss: [            // Array of paths to custom CSS files
+      // '/assets/css/custom.css', // Custom TOC styles
+    ]
   },
+
+  // Custom JavaScript Files
+  customJs: [  // Array of paths to custom JS files, loaded at end of body
+    // '/assets/js/custom-script.js', // Paths relative to outputDir root
+  ],
+
+  // Plugins Configuration
+  // Plugins are configured here. docmd will look for these keys.
+  plugins: {
+    // SEO Plugin Configuration
+    // Most SEO data is pulled from page frontmatter (title, description, image, etc.)
+    // These are fallbacks or site-wide settings.
+    seo: {
+      // Default meta description if a page doesn't have one in its frontmatter
+      defaultDescription: 'docmd is a Node.js command-line tool for generating beautiful, lightweight static documentation sites from Markdown files.',
+      openGraph: { // For Facebook, LinkedIn, etc.
+        // siteName: 'docmd Documentation', // Optional, defaults to config.siteTitle
+        // Default image for og:image if not specified in page frontmatter
+        // Path relative to outputDir root
+        defaultImage: '/assets/images/docmd-preview.png',
+      },
+      twitter: { // For Twitter Cards
+        cardType: 'summary_large_image',     // 'summary', 'summary_large_image'
+        // siteUsername: '@docmd_handle',    // Your site's Twitter handle (optional)
+        // creatorUsername: '@your_handle',  // Default author handle (optional, can be overridden in frontmatter)
+      }
+    },
+    // Analytics Plugin Configuration
+    analytics: {
+      // Google Analytics 4 (GA4)
+      googleV4: {
+        measurementId: 'G-8QVBDQ4KM1' // Replace with your actual GA4 Measurement ID
+      }
+    },
+    // Enable Sitemap plugin
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    }
+    // Add other future plugin configurations here by their key
+  },
+
+  // Navigation Structure (Sidebar)
+  // Icons are kebab-case names from Lucide Icons (https://lucide.dev/)
   navigation: [
-    { title: 'Home', path: '/' }, // Corresponds to docs/index.md
-    // {
-    //   title: 'Category',
-    //   children: [
-    //     { title: 'Page 1', path: '/category/page1' },
-    //   ],
-    // },
+      { title: 'Welcome', path: '/', icon: 'home' }, // Corresponds to docs/index.md
+      // External links:
+      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
+      { title: 'Documentation', path: 'https://github.com/mgks/docmd', icon: 'scroll', external: true }
   ],
+
+  // Footer Configuration
+  // Markdown is supported here.
+  footer: '© ' + new Date().getFullYear() + ' Project.',
+
+  // Favicon Configuration
+  // Path relative to outputDir root
+  favicon: '/assets/favicon.ico',
 };
 `;
 

package/src/core/file-processor.js

@@ -4,6 +4,7 @@ const MarkdownIt = require('markdown-it');
 const matter = require('gray-matter');
 const hljs = require('highlight.js');
 const container = require('markdown-it-container');
+const attrs = require('markdown-it-attrs');
 
 const md = new MarkdownIt({
   html: true,
@@ -23,6 +24,45 @@ const md = new MarkdownIt({
   }
 });
 
+// Add markdown-it-attrs for image styling and other element attributes
+// This allows for {.class} syntax after elements
+md.use(attrs, {
+  // Allow attributes on images and other elements
+  leftDelimiter: '{',
+  rightDelimiter: '}',
+  allowedAttributes: ['class', 'id', 'width', 'height', 'style']
+});
+
+// Custom image renderer to ensure attributes are properly applied
+const defaultImageRenderer = md.renderer.rules.image;
+md.renderer.rules.image = function(tokens, idx, options, env, self) {
+  // Get the rendered HTML from the default renderer
+  const renderedImage = defaultImageRenderer(tokens, idx, options, env, self);
+  
+  // Check if the next token is an attrs_block
+  const nextToken = tokens[idx + 1];
+  if (nextToken && nextToken.type === 'attrs_block') {
+    // Extract attributes from the attrs_block token
+    const attrs = nextToken.attrs || [];
+    
+    // Build the attributes string
+    const attrsStr = attrs.map(([name, value]) => {
+      if (name === 'class') {
+        return `class="${value}"`;
+      } else if (name.startsWith('data-')) {
+        return `${name}="${value}"`;
+      } else {
+        return `${name}="${value}"`;
+      }
+    }).join(' ');
+    
+    // Insert attributes into the image tag
+    return renderedImage.replace('<img ', `<img ${attrsStr} `);
+  }
+  
+  return renderedImage;
+};
+
 // Add anchors to headings for TOC linking
 md.use((md) => {
   // Original renderer

package/src/core/html-generator.js

@@ -23,8 +23,8 @@ async function processPluginHooks(config, pageData, relativePathToRoot) {
 
     // 2. Theme CSS (built-in handling for theme.name)
     if (config.theme && config.theme.name && config.theme.name !== 'default') {
-        // Assumes theme CSS files are like 'theme-yourthemename.css' in assets/css
-        const themeCssPath = `assets/css/theme-${config.theme.name}.css`;
+        // Assumes theme CSS files are like 'docmd-theme-yourthemename.css' in assets/css
+        const themeCssPath = `assets/css/docmd-theme-${config.theme.name}.css`;
         // Check if theme file exists before linking (optional, good practice)
         // For now, assume it will exist if specified.
         themeCssLinkHtml = `  <link rel="stylesheet" href="${relativePathToRoot}${themeCssPath}">\n`;
@@ -109,7 +109,9 @@ async function generateHtmlPage(templateData) {
     };
 
     try {
-        return ejs.render(layoutTemplate, ejsData);
+        return ejs.render(layoutTemplate, ejsData, {
+            filename: layoutTemplatePath // Add filename for proper include resolution
+        });
     } catch (e) {
         console.error(`❌ Error rendering EJS template for ${outputPath}: ${e.message}`);
         console.error("EJS Data:", JSON.stringify(ejsData, null, 2).substring(0, 1000) + "..."); // Log partial data
@@ -133,6 +135,8 @@ async function generateNavigationHtml(navItems, currentPagePath, relativePathToR
         relativePathToRoot,
         config, // Pass full config if needed by nav (e.g. for base path)
         ...ejsHelpers
+    }, {
+        filename: navTemplatePath // Add filename for proper include resolution
     });
 }
 

package/src/templates/layout.ejs

@@ -13,9 +13,9 @@
 
     <%- faviconLinkHtml || '' %> <%# Favicon %>
 
-    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/main.css">
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/docmd-main.css">
 
-    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/highlight-<%= defaultMode === 'dark' ? 'dark' : 'light' %>.css" id="highlight-theme">
+    <link rel="stylesheet" href="<%= relativePathToRoot %>assets/css/docmd-highlight-<%= defaultMode === 'dark' ? 'dark' : 'light' %>.css" id="highlight-theme">
 
     <%- themeCssLinkHtml || '' %> <%# For theme.name specific CSS %>
 
@@ -90,65 +90,7 @@
                 
                 <!-- 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>
-                      <% } 
-                    } %>
+                    <%- include('toc', { content, headings, navigationHtml, isActivePage }) %>
                 </div>
             </div>
         </main>
@@ -164,7 +106,7 @@
         </footer>
     </div>
 
-    <script src="<%= relativePathToRoot %>assets/js/theme-toggle.js"></script>
+    <script src="<%= relativePathToRoot %>assets/js/docmd-theme-toggle.js"></script>
     <% (customJsFiles || []).forEach(jsFile => { %>
       <script src="<%= relativePathToRoot %><%- jsFile.startsWith('/') ? jsFile.substring(1) : jsFile %>"></script>
     <% }); %>

package/src/templates/toc.ejs

@@ -1,34 +1,67 @@
 <%# 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 });
-  }
+// 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 if there are enough headings
-if (tocHeadings.length > 1) { 
+// Use the isActivePage flag if provided, otherwise fall back to checking navigationHtml
+const shouldShowToc = typeof isActivePage !== 'undefined' ? isActivePage : 
+                      (typeof navigationHtml !== 'undefined' && navigationHtml && navigationHtml.includes('class="active"'));
+
+if (shouldShowToc) {
+  // 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;
+    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
+      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>
+          <a href="#<%= heading.id %>" class="toc-link"><%- heading.text %></a>
         </li>
       <% }); %>
     </ul>
   </div>
-<% } %> 
+<% } 
+} %> 

package/docs/writing-content/index.md

@@ -1,17 +0,0 @@
----
-title: "Writing Content with docmd"
-description: "Learn how to write effective documentation using Markdown, frontmatter, and custom components in docmd."
----
-
-# Writing Content
-
-`docmd` is designed to let you focus on your content, written in standard Markdown. This section covers the essentials of creating pages, structuring your content, and leveraging `docmd`'s features to enhance your documentation.
-
-## Key Aspects:
-
-*   **[Frontmatter](/writing-content/frontmatter/):** Define page-specific metadata like titles and descriptions using simple YAML at the top of your Markdown files.
-*   **[Markdown Syntax](/writing-content/markdown-syntax/):** Utilize standard CommonMark and GitHub Flavored Markdown for formatting your text, code blocks, lists, tables, and more.
-*   **[Custom Containers](/writing-content/custom-containers/):** Enhance your pages with special components like callouts, cards, and steps using a simple `::: name :::` syntax.
-*   **[Steps Container](/writing-content/steps-test/):** Create sequential guides with the specialized steps container.
-
-By understanding these elements, you can create rich, well-structured, and engaging documentation.

package/src/assets/css/toc.css

@@ -1,76 +0,0 @@
-/* TOC Styles - Simplified Hyperlink Style */
-.toc-container {
-    margin: 0;
-    padding: 0;
-    border: none;
-    background-color: transparent;
-  }
-  
-  .toc-title {
-      margin-top: 0;
-      margin-bottom: 0.5rem;
-      font-size: 1rem;
-      font-weight: bold;
-      color: var(--text-muted);
-  
-  }
-  
-  .toc-list {
-    list-style: none;
-    padding-left: 0;
-    margin: 0;
-  }
-  
-  .toc-item {
-    margin-bottom: 0.25rem;
-    line-height: 1.4;
-  }
-  
-  .toc-link {
-      text-decoration: none;
-      color: var(--link-color);
-      display: inline-block;
-      padding: 0.1rem 0;
-      font-size: 0.9rem;
-      font-weight: 500;
-  
-  }
-  
-  .toc-link:hover {
-    text-decoration: underline;
-  }
-  
-  /* Indentation for different heading levels */
-  .toc-level-2 {
-    margin-left: 0;
-  }
-  
-  .toc-level-3 {
-    margin-left: 0.75rem;
-    font-size: 0.85rem;
-  }
-  
-  .toc-level-4 {
-    margin-left: 1.5rem;
-    font-size: 0.8rem;
-  }
-  
-  /* TOC sidebar should only display on active pages */
-  .toc-sidebar {
-      width: 180px;
-      position: sticky;
-      top: 2rem;
-      max-height: calc(100vh - 4rem);
-      overflow-y: auto;
-      align-self: flex-start;
-  
-  }
-  
-  /* Hide TOC on mobile */
-  @media (max-width: 1024px) {
-    .toc-sidebar {
-      width: 100%;
-      position: static;
-      margin-bottom: 1rem;
-    }
-  }