@mgks/docmd 0.1.3 → 0.2.0

package/src/core/html-generator.js

@@ -23,14 +23,10 @@ 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 '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`;
     }
 
-
     // 3. SEO Plugin (if configured)
     if (config.plugins?.seo) {
         metaTagsHtml += generateSeoMetaTags(config, pageData, relativePathToRoot);
@@ -43,9 +39,6 @@ async function processPluginHooks(config, pageData, relativePathToRoot) {
         pluginBodyScriptsHtml += analyticsScripts.bodyScriptsHtml;
     }
 
-    // Future: Loop through a more generic plugin array if you evolve the system
-    // for (const plugin of config.activePlugins) { /* plugin.runHook('meta', ...) */ }
-
     return {
         metaTagsHtml,
         faviconLinkHtml,
@@ -58,11 +51,13 @@ async function processPluginHooks(config, pageData, relativePathToRoot) {
 
 async function generateHtmlPage(templateData) {
     const {
-        content, pageTitle, siteTitle, navigationHtml,
+        content, siteTitle, navigationHtml,
         relativePathToRoot, config, frontmatter, outputPath,
         prevPage, nextPage, currentPagePath, headings
     } = templateData;
 
+    const pageTitle = frontmatter.title; // Get title from frontmatter (already processed in file-processor)
+
     // Process plugins to get their HTML contributions
     const pluginOutputs = await processPluginHooks(
         config,
@@ -75,16 +70,9 @@ async function generateHtmlPage(templateData) {
         footerHtml = mdInstance.renderInline(config.footer);
     }
 
-    // Determine which template to use based on frontmatter
     let templateName = 'layout.ejs';
     if (frontmatter.noStyle === true) {
         templateName = 'no-style.ejs';
-        
-        // For no-style pages, ensure we're passing the raw HTML content
-        // without any additional processing or escaping
-        if (content.includes('&lt;') || content.includes('&gt;')) {
-            console.warn(`⚠️ Warning: HTML content in no-style page appears to be escaped. This may cause rendering issues.`);
-        }
     }
 
     const layoutTemplatePath = path.join(__dirname, '..', 'templates', templateName);
@@ -93,42 +81,45 @@ async function generateHtmlPage(templateData) {
     }
     const layoutTemplate = await fs.readFile(layoutTemplatePath, 'utf8');
 
-    // Determine if this is an active page for TOC display
-    // The currentPagePath exists and has content
     const isActivePage = currentPagePath && content && content.trim().length > 0;
 
     const ejsData = {
         content,
-        pageTitle: frontmatter.title || pageTitle || 'Untitled', // Ensure pageTitle is robust
-        description: frontmatter.description, // Used by layout if no SEO plugin overrides
+        pageTitle, // Pass the potentially undefined title
+        description: frontmatter.description,
         siteTitle,
         navigationHtml,
         defaultMode: config.theme?.defaultMode || 'light',
         relativePathToRoot,
         logo: config.logo,
+        sidebarConfig: { 
+            collapsible: config.sidebar?.collapsible ?? false,
+            defaultCollapsed: config.sidebar?.defaultCollapsed ?? false,
+        },
         theme: config.theme,
         customCssFiles: config.theme?.customCss || [],
         customJsFiles: config.customJs || [],
+        sponsor: config.sponsor,
         footer: config.footer,
         footerHtml,
         renderIcon,
         prevPage,
         nextPage,
-        currentPagePath, // Pass the current page path for active state detection
-        headings: headings || [], // Pass headings for TOC, default to empty array if not provided
-        isActivePage, // Flag to determine if TOC should be shown
-        frontmatter, // Pass the entire frontmatter for no-style template
-        ...pluginOutputs, // Spread all plugin generated HTML strings
+        currentPagePath,
+        headings: headings || [],
+        isActivePage,
+        frontmatter,
+        ...pluginOutputs,
     };
 
     try {
         return ejs.render(layoutTemplate, ejsData, {
-            filename: layoutTemplatePath // Add filename for proper include resolution
+            filename: layoutTemplatePath
         });
     } 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
-        throw e; // Re-throw to stop build
+        console.error("EJS Data:", JSON.stringify(ejsData, null, 2).substring(0, 1000) + "...");
+        throw e;
     }
 }
 
@@ -139,17 +130,16 @@ async function generateNavigationHtml(navItems, currentPagePath, relativePathToR
     }
     const navTemplate = await fs.readFile(navTemplatePath, 'utf8');
 
-    // Make renderIcon available to the EJS template
     const ejsHelpers = { renderIcon };
 
     return ejs.render(navTemplate, {
         navItems,
         currentPagePath,
         relativePathToRoot,
-        config, // Pass full config if needed by nav (e.g. for base path)
+        config,
         ...ejsHelpers
     }, {
-        filename: navTemplatePath // Add filename for proper include resolution
+        filename: navTemplatePath
     });
 }
 

package/src/plugins/seo.js

@@ -19,6 +19,10 @@ function generateSeoMetaTags(config, pageData, relativePathToRoot) {
   
     metaTagsHtml += `  <meta name="description" content="${description}">\n`;
   
+    // Canonical URL - use permalink first, fall back to canonicalUrl, then default to pageUrl
+    const canonicalUrl = frontmatter.permalink || frontmatter.canonicalUrl || pageUrl;
+    metaTagsHtml += `  <link rel="canonical" href="${canonicalUrl}">\n`;
+  
     // Open Graph
     metaTagsHtml += `  <meta property="og:title" content="${pageTitle} | ${siteTitle}">\n`;
     metaTagsHtml += `  <meta property="og:description" content="${description}">\n`;

package/src/templates/layout.ejs

@@ -6,7 +6,7 @@
 
     <%- metaTagsHtml || '' %> <%# SEO Plugin Meta Tags %>
 
-    <title><%= pageTitle %> | <%= siteTitle %></title>
+    <title><%= pageTitle %> : <%= siteTitle %></title>
     <% if (description && !(metaTagsHtml && metaTagsHtml.includes('name="description"'))) { %>
       <meta name="description" content="<%= description %>">
     <% } %>
@@ -27,7 +27,7 @@
 
     <%- pluginHeadScriptsHtml || '' %> <%# Plugin specific head scripts (e.g., Analytics) %>
 </head>
-<body data-theme="<%= defaultMode %>">
+<body class="<%= sidebarConfig.collapsible ? 'sidebar-collapsible' : 'sidebar-not-collapsible' %>" data-theme="<%= defaultMode %>" data-default-collapsed="<%= sidebarConfig.defaultCollapsed %>">
     <aside class="sidebar">
         <div class="sidebar-header">
             <% if (logo && logo.light && logo.dark) { %>
@@ -40,7 +40,7 @@
             <% } %>
         </div>
         <%- navigationHtml %>
-        <% if (theme && theme.enableModeToggle) { %>
+        <% if (theme && theme.enableModeToggle && theme.positionMode !== 'top') { %>
           <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' }) %>
@@ -49,9 +49,25 @@
         <% } %>
     </aside>
     <div class="main-content-wrapper">
-        <header class="page-header">
-            <h1><%= pageTitle %></h1>
-        </header>
+        <div class="page-header">
+            <div class="header-left">
+                <% if (sidebarConfig.collapsible) { %>
+                <button id="sidebar-toggle-button" class="sidebar-toggle-button" aria-label="Toggle Sidebar">
+                    <%- renderIcon('panel-left-close') %>
+                </button>
+                <% } %>
+                <h1><%= pageTitle %></h1>
+            </div>
+            <% if (theme && theme.enableModeToggle && theme.positionMode === 'top') { %>
+            <div class="header-right">
+                <button id="theme-toggle-button" aria-label="Toggle theme" class="theme-toggle-button theme-toggle-header">
+                    <%# renderIcon is available in the global EJS scope from html-generator %>
+                    <%- renderIcon('sun', { class: 'icon-sun' }) %>
+                    <%- renderIcon('moon', { class: 'icon-moon' }) %>
+                </button>
+            </div>
+            <% } %>
+        </div>
         <main class="content-area">
             <div class="content-layout">
                 <div class="main-content">
@@ -106,11 +122,21 @@
         </footer>
     </div>
 
-    <script src="<%= relativePathToRoot %>assets/js/docmd-theme-toggle.js"></script>
+    <script src="<%= relativePathToRoot %>assets/js/docmd-main.js"></script>
+
     <% (customJsFiles || []).forEach(jsFile => { %>
       <script src="<%= relativePathToRoot %><%- jsFile.startsWith('/') ? jsFile.substring(1) : jsFile %>"></script>
     <% }); %>
 
-    <%- pluginBodyScriptsHtml || '' %> <%# Plugin specific body scripts %>
+    <%- pluginBodyScriptsHtml || '' %>
+    
+    <% if (sponsor && sponsor.enabled) { %>
+    <div class="sponsor-ribbon">
+        <a href="<%= sponsor.link %>" target="_blank" rel="noopener noreferrer" class="sponsor-link">
+            <%- renderIcon('heart', { class: 'sponsor-icon' }) %>
+            <span class="sponsor-text"><%= sponsor.title %></span>
+        </a>
+    </div>
+    <% } %>
 </body>
 </html>

package/docs/content/custom-containers.md

@@ -1,129 +0,0 @@
----
-title: "Custom Containers"
-description: "Enhance your documentation with special components like callouts, cards, and steps using docmd's custom container syntax."
----
-
-# Custom Containers
-
-`docmd` provides a simple syntax for adding richer, pre-styled components to your Markdown content using "custom containers." These are powered by the `markdown-it-container` plugin.
-
-The general syntax is:
-
-```
-::: containerName [optionalTitleOrType]
-Content for the container goes here.
-It can span **multiple lines** and include other *Markdown* elements.
-:::
-```
-
-## Callouts
-
-Callouts are useful for highlighting important information, warnings, tips, or notes.
-
-**Syntax:**
-```
-::: callout type
-Content of the callout.
-:::
-```
-*   `type`: Can be `info`, `warning`, `tip`, or `danger`.
-
-**Examples:**
-
-::: callout info
-This is an informational message. It's good for general notes or neutral supplementary details.
-:::
-
-::: callout warning
-**Watch out!** This indicates something that requires caution or might lead to unexpected results if ignored.
-:::
-
-::: callout tip
-Here's a helpful tip or a best practice suggestion to improve a process or understanding.
-:::
-
-::: callout danger
-**Critical!** This highlights a potential risk, a destructive action, or something that must be avoided.
-:::
-
-## Cards
-
-Cards provide a visually distinct block for grouping related content, often with a title.
-
-**Syntax:**
-```
-::: card Optional Card Title
-The main body content of the card.
-Supports **Markdown** formatting.
-- List item 1
-- List item 2
-:::
-```
-*   `Optional Card Title`: If provided after `card`, it becomes the title of the card.
-
-**Example:**
-
-::: card My Feature Overview
-This card describes an amazing feature.
-* It's easy to use.
-* It solves a common problem.
-
-Learn more by reading the full guide.
-:::
-
-::: card
-This is a card without an explicit title. The content starts directly.
-Ideal for small, self-contained snippets.
-:::
-
-## Steps
-
-The "steps" container is designed for presenting a sequence of actions or instructions, often in a numbered or ordered fashion.
-
-**Syntax:**
-
-```
-::: steps
-> 1. **First Step Title:**
-> Description of the first step.
-
-> 2. **Second Step Title:**
-> Description of the second step.
-
-> *. **Using Asterisk:**
-> Alternative numbering style.
-
-> **No Number:**
-> Without a number.
-:::
-```
-
-**How it works:**
-
-The steps container uses blockquotes (`>`) to define individual steps. Start each step with a number or asterisk followed by a period, then the step title in bold. The content after the title becomes the step content.
-
-**Example:**
-
-::: steps
-> 1. **Install Dependencies:**
-> First, make sure you have Node.js and npm installed. Then, run:
->
-> ```bash
-> npm install my-package
-> ```
-
-> 2. **Configure the Settings:**
-> Open the `config.json` file and update the `apiKey` with your credentials.
-
-> 3. **Run the Application:**
-> Start the application using:
->
-> ```bash
-> npm start
-> ```
->
-> You should see "Application started successfully!" in your console.
-:::
-:::
-
-These custom containers allow you to create more engaging and structured documentation without needing to write custom HTML or CSS for common patterns. Experiment with them to see how they can improve your content's clarity and visual appeal.

package/src/assets/js/docmd-theme-toggle.js

@@ -1,59 +0,0 @@
-// src/assets/js/theme-toggle.js
-function applyTheme(theme, isInitialLoad = false) {
-  document.body.setAttribute('data-theme', theme);
-  if (!isInitialLoad) {
-    localStorage.setItem('docmd-theme', theme);
-  }
-
-  // Change highlight.js theme dynamically (if separate themes are loaded)
-  const highlightThemeLink = document.getElementById('highlight-theme');
-  if (highlightThemeLink) {
-    const isDark = theme.includes('dark');
-    const isLight = theme.includes('light');
-    const currentHref = highlightThemeLink.href;
-    
-    if (isDark && currentHref.includes('docmd-highlight-light.css')) {
-      highlightThemeLink.href = currentHref.replace('docmd-highlight-light.css', 'docmd-highlight-dark.css');
-    } else if (isLight && currentHref.includes('docmd-highlight-dark.css')) {
-      highlightThemeLink.href = currentHref.replace('docmd-highlight-dark.css', 'docmd-highlight-light.css');
-    }
-  }
-}
-
-function getInitialTheme() {
-  const storedTheme = localStorage.getItem('docmd-theme');
-  if (storedTheme) {
-    return storedTheme;
-  }
-  // The server sets the initial data-theme based on config.theme.defaultMode.
-  // We respect localStorage first, then what the server provided.
-  // Optionally, could check prefers-color-scheme if neither is set, but defaultMode covers this.
-  return document.body.getAttribute('data-theme') || 'light';
-}
-
-document.addEventListener('DOMContentLoaded', () => {
-  // Apply initial theme (respecting localStorage over server-rendered if set)
-  const initialTheme = getInitialTheme();
-  applyTheme(initialTheme, true); // true indicates it's the initial load
-
-  const themeToggleButton = document.getElementById('theme-toggle-button');
-  if (themeToggleButton) {
-    themeToggleButton.addEventListener('click', () => {
-      let currentTheme = document.body.getAttribute('data-theme');
-      
-      // Handle both regular themes and sky theme variants
-      let newTheme;
-      if (currentTheme === 'light') {
-        newTheme = 'dark';
-      } else if (currentTheme === 'dark') {
-        newTheme = 'light';
-      } else if (currentTheme === 'sky-light') {
-        newTheme = 'sky-dark';
-      } else if (currentTheme === 'sky-dark') {
-        newTheme = 'sky-light';
-      }
-      
-      applyTheme(newTheme); // isInitialLoad is false here, so it saves to localStorage
-    });
-  }
-});