@mgks/docmd 0.1.0

package/src/commands/build.js

@@ -0,0 +1,300 @@
+// src/commands/build.js
+const fs = require('fs-extra');
+const path = require('path');
+const { loadConfig } = require('../core/config-loader');
+const { processMarkdownFile } = require('../core/file-processor');
+const { generateHtmlPage, generateNavigationHtml } = require('../core/html-generator');
+const { renderIcon, clearWarnedIcons } = require('../core/icon-renderer'); // Update import
+const { generateSitemap } = require('../plugins/sitemap'); // Import our sitemap plugin
+
+// Debug function to log navigation information
+function logNavigationPaths(pagePath, navPath, normalizedPath) {
+  console.log(`\nPage: ${pagePath}`);
+  console.log(`Navigation Path: ${navPath}`);
+  console.log(`Normalized Path: ${normalizedPath}`);
+}
+
+// Add a global or scoped flag to track if the warning has been shown in the current dev session
+let highlightWarningShown = false;
+
+async function buildSite(configPath, options = { isDev: false }) {
+  clearWarnedIcons(); // Clear warnings at the start of every build
+
+  const config = await loadConfig(configPath);
+  const CWD = process.cwd();
+  const SRC_DIR = path.resolve(CWD, config.srcDir);
+  const OUTPUT_DIR = path.resolve(CWD, config.outputDir);
+
+  if (!await fs.pathExists(SRC_DIR)) {
+    throw new Error(`Source directory not found: ${SRC_DIR}`);
+  }
+
+  await fs.emptyDir(OUTPUT_DIR);
+  if (!options.isDev) {
+    console.log(`🧹 Cleaned output directory: ${OUTPUT_DIR}`);
+  }
+
+  const assetsSrcDir = path.join(__dirname, '..', 'assets');
+  const assetsDestDir = path.join(OUTPUT_DIR, 'assets');
+  if (await fs.pathExists(assetsSrcDir)) {
+    await fs.copy(assetsSrcDir, assetsDestDir);
+    if (!options.isDev) {
+        console.log(`📂 Copied assets to ${assetsDestDir}`);
+    }
+  } else {
+    console.warn(`⚠️  Assets source directory not found: ${assetsSrcDir}`);
+  }
+
+  // Check for Highlight.js themes
+  const lightThemePath = path.join(__dirname, '..', 'assets', 'css', 'highlight-light.css');
+  const darkThemePath = path.join(__dirname, '..', 'assets', 'css', 'highlight-dark.css');
+
+  const themesMissing = !await fs.pathExists(lightThemePath) || !await fs.pathExists(darkThemePath);
+
+  if (themesMissing) {
+    // For 'docmd build', always show.
+    // For 'docmd dev', show only once per session if not already shown.
+    if (!options.isDev || (options.isDev && !highlightWarningShown)) {
+      console.warn(`⚠️ Highlight.js themes not found in assets. Please ensure these files exist:
+      - ${lightThemePath}
+      - ${darkThemePath}
+    Syntax highlighting may not work correctly.`);
+      if (options.isDev) {
+        highlightWarningShown = true; // Mark as shown for this dev session
+      }
+    }
+  }
+
+
+  const markdownFiles = await findMarkdownFiles(SRC_DIR);
+  if (markdownFiles.length === 0) {
+      console.warn(`⚠️ No Markdown files found in ${SRC_DIR}. Nothing to build.`);
+      return;
+  }
+  if (!options.isDev) {
+    console.log(`📄 Found ${markdownFiles.length} markdown files.`);
+  }
+
+  // Array to collect information about all processed pages for sitemap
+  const processedPages = [];
+  
+  // Extract a flattened navigation array for prev/next links
+  const flatNavigation = [];
+  
+  // Helper function to create a normalized path for navigation matching
+  function createNormalizedPath(item) {
+    if (!item.path) return null;
+    return item.path.startsWith('/') ? item.path : '/' + item.path;
+  }
+  
+  function extractNavigationItems(items, parentPath = '') {
+    if (!items || !Array.isArray(items)) return;
+    
+    for (const item of items) {
+      if (item.external) continue; // Skip external links
+      
+      // Only include items with paths (not section headers without links)
+      if (item.path) {
+        // Normalize path - ensure leading slash
+        let normalizedPath = createNormalizedPath(item);
+        
+        // For parent items with children, ensure path ends with / (folders)
+        // This helps with matching in the navigation template
+        if (item.children && item.children.length > 0) {
+          // If path from config doesn't end with slash, add it
+          if (!item.path.endsWith('/') && !normalizedPath.endsWith('/')) {
+            normalizedPath += '/';
+          }
+        }
+        
+        flatNavigation.push({
+          title: item.title,
+          path: normalizedPath,
+          fullPath: item.path, // Original path as defined in config
+          isParent: item.children && item.children.length > 0 // Mark if it's a parent with children
+        });
+      }
+      
+      // Process children (depth first to maintain document outline order)
+      if (item.children && Array.isArray(item.children)) {
+        extractNavigationItems(item.children, item.path || parentPath);
+      }
+    }
+  }
+  
+  // Extract navigation items into flat array
+  extractNavigationItems(config.navigation);
+
+  for (const mdFilePath of markdownFiles) {
+    const relativeMdPath = path.relative(SRC_DIR, mdFilePath);
+    
+    // Pretty URL handling - properly handle index.md files in subfolders
+    let outputHtmlPath;
+    const fileName = path.basename(relativeMdPath);
+    const isIndexFile = fileName === 'index.md';
+    
+    if (isIndexFile) {
+      // For any index.md file (in root or subfolder), convert to index.html in the same folder
+      const dirPath = path.dirname(relativeMdPath);
+      outputHtmlPath = path.join(dirPath, 'index.html');
+    } else {
+      // For non-index files, create a folder with index.html
+      outputHtmlPath = relativeMdPath.replace(/\.md$/, '/index.html');
+    }
+
+    const finalOutputHtmlPath = path.join(OUTPUT_DIR, outputHtmlPath);
+
+    const depth = outputHtmlPath.split(path.sep).length - 1;
+    const relativePathToRoot = depth > 0 ? '../'.repeat(depth) : './';
+
+    const { frontmatter, htmlContent, headings } = await processMarkdownFile(mdFilePath);
+    
+    // Get the URL path for navigation
+    let currentPagePathForNav;
+    let normalizedPath;
+    
+    if (isIndexFile) {
+      // For index.md files, the nav path should be the directory itself with trailing slash
+      const dirPath = path.dirname(relativeMdPath);
+      if (dirPath === '.') {
+        // Root index.md
+        currentPagePathForNav = 'index.html';
+        normalizedPath = '/';
+      } else {
+        // Subfolder index.md - simple format: directory-name/
+        currentPagePathForNav = dirPath + '/'; 
+        normalizedPath = '/' + dirPath;
+      }
+    } else {
+      // For non-index files, the path should be the file name with trailing slash
+      const pathWithoutExt = relativeMdPath.replace(/\.md$/, '');
+      currentPagePathForNav = pathWithoutExt + '/';
+      normalizedPath = '/' + pathWithoutExt;
+    }
+    
+    // Convert Windows backslashes to forward slashes for web paths
+    currentPagePathForNav = currentPagePathForNav.replace(/\\/g, '/');
+
+    // Log navigation paths for debugging
+    // Uncomment this line when debugging:
+    // logNavigationPaths(mdFilePath, currentPagePathForNav, normalizedPath);
+
+    const navigationHtml = await generateNavigationHtml(
+      config.navigation,
+      currentPagePathForNav,
+      relativePathToRoot,
+      config
+    );
+
+    // Find current page in navigation for prev/next links
+    let prevPage = null;
+    let nextPage = null;
+    let currentPageIndex = -1;
+    
+    // Find the current page in flatNavigation
+    currentPageIndex = flatNavigation.findIndex(item => {
+      // Direct path match
+      if (item.path === normalizedPath) {
+        return true;
+      }
+      
+      // Special handling for parent folders
+      if (isIndexFile && item.path.endsWith('/')) {
+        // Remove trailing slash for comparison
+        const itemPathWithoutSlash = item.path.slice(0, -1);
+        return itemPathWithoutSlash === normalizedPath;
+      }
+      
+      return false;
+    });
+
+    if (currentPageIndex >= 0) {
+      // Get previous and next pages if they exist
+      if (currentPageIndex > 0) {
+        prevPage = flatNavigation[currentPageIndex - 1];
+      }
+      
+      if (currentPageIndex < flatNavigation.length - 1) {
+        nextPage = flatNavigation[currentPageIndex + 1];
+      }
+    }
+    
+    // Convert page paths to proper URLs for links
+    if (prevPage) {
+      // Format the previous page URL, avoiding double slashes
+      if (prevPage.path === '/') {
+        prevPage.url = relativePathToRoot + 'index.html';
+      } else {
+        // Remove leading slash and ensure clean path
+        const cleanPath = prevPage.path.substring(1).replace(/\/+$/, '');
+        prevPage.url = relativePathToRoot + cleanPath + '/';
+      }
+    }
+    
+    if (nextPage) {
+      // Format the next page URL, avoiding double slashes
+      if (nextPage.path === '/') {
+        nextPage.url = relativePathToRoot + 'index.html';
+      } else {
+        // Remove leading slash and ensure clean path
+        const cleanPath = nextPage.path.substring(1).replace(/\/+$/, '');
+        nextPage.url = relativePathToRoot + cleanPath + '/';
+      }
+    }
+
+    const pageDataForTemplate = {
+      content: htmlContent,
+      pageTitle: frontmatter.title || 'Untitled',
+      siteTitle: config.siteTitle,
+      navigationHtml,
+      relativePathToRoot: relativePathToRoot,
+      config: config, // Pass full config
+      frontmatter: frontmatter,
+      outputPath: outputHtmlPath, // Relative path from outputDir root
+      prettyUrl: true, // Flag to indicate we're using pretty URLs
+      prevPage: prevPage, // Previous page in navigation
+      nextPage: nextPage, // Next page in navigation
+      currentPagePath: normalizedPath, // Pass the normalized path for active state detection
+      headings: headings || [], // Pass headings for TOC
+    };
+
+    const pageHtml = await generateHtmlPage(pageDataForTemplate);
+
+    await fs.ensureDir(path.dirname(finalOutputHtmlPath));
+    await fs.writeFile(finalOutputHtmlPath, pageHtml);
+
+    // Add to processed pages for sitemap
+    processedPages.push({
+      outputPath: isIndexFile 
+        ? (path.dirname(relativeMdPath) === '.' ? 'index.html' : path.dirname(relativeMdPath) + '/')
+        : outputHtmlPath.replace(/\\/g, '/').replace(/\/index\.html$/, '/'),
+      frontmatter: frontmatter
+    });
+  }
+
+  // Generate sitemap if enabled in config
+  if (config.plugins?.sitemap !== false) {
+    try {
+      await generateSitemap(config, processedPages, OUTPUT_DIR);
+    } catch (error) {
+      console.error(`❌ Error generating sitemap: ${error.message}`);
+    }
+  }
+}
+
+// findMarkdownFiles function remains the same
+async function findMarkdownFiles(dir) {
+  let files = [];
+  const items = await fs.readdir(dir, { withFileTypes: true });
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    if (item.isDirectory()) {
+      files = files.concat(await findMarkdownFiles(fullPath));
+    } else if (item.isFile() && (item.name.endsWith('.md') || item.name.endsWith('.markdown'))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+module.exports = { buildSite };

package/src/commands/dev.js

@@ -0,0 +1,182 @@
+// src/commands/dev.js
+const express = require('express');
+const http = require('http');
+const WebSocket = require('ws');
+const chokidar = require('chokidar');
+const path = require('path');
+const fs = require('fs-extra');
+const { buildSite } = require('./build'); // Re-use the build logic
+const { loadConfig } = require('../core/config-loader');
+
+async function startDevServer(configPathOption) {
+  let config = await loadConfig(configPathOption); // Load initial config
+  const CWD = process.cwd(); // Current Working Directory where user runs `docmd dev`
+
+  // Function to resolve paths based on current config
+  const resolveConfigPaths = (currentConfig) => {
+    return {
+      outputDir: path.resolve(CWD, currentConfig.outputDir),
+      srcDirToWatch: path.resolve(CWD, currentConfig.srcDir),
+      configFileToWatch: path.resolve(CWD, configPathOption), // Path to the config file itself
+    };
+  };
+
+  let paths = resolveConfigPaths(config);
+
+  // docmd's internal templates and assets (for live dev of docmd itself)
+  const DOCMD_TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
+  const DOCMD_ASSETS_DIR = path.resolve(__dirname, '..', 'assets');
+
+  const app = express();
+  const server = http.createServer(app);
+  const wss = new WebSocket.Server({ server });
+
+  let wsClients = new Set();
+  wss.on('connection', (ws) => {
+    wsClients.add(ws);
+    // console.log('Client connected to WebSocket. Total clients:', wsClients.size);
+    ws.on('close', () => {
+      wsClients.delete(ws);
+      // console.log('Client disconnected. Total clients:', wsClients.size);
+    });
+    ws.on('error', (error) => {
+        console.error('WebSocket error on client:', error);
+    });
+  });
+  wss.on('error', (error) => {
+    console.error('WebSocket Server error:', error);
+  });
+
+
+  function broadcastReload() {
+    // console.log('Broadcasting reload to', wsClients.size, 'clients');
+    wsClients.forEach(client => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send('reload');
+      }
+    });
+  }
+
+  // Inject live reload script into HTML
+  app.use((req, res, next) => {
+    if (req.path.endsWith('.html')) {
+      const originalSend = res.send;
+      res.send = function (body) {
+        if (typeof body === 'string') {
+          const liveReloadScript = `
+            <script>
+              const socket = new WebSocket(\`ws://\${window.location.host}\`);
+              socket.onmessage = function(event) { if (event.data === 'reload') window.location.reload(); };
+              socket.onerror = function(error) { console.error('WebSocket Client Error:', error); };
+              // socket.onopen = function() { console.log('WebSocket Client Connected'); };
+              // socket.onclose = function() { console.log('WebSocket Client Disconnected'); };
+            </script>
+          `;
+          body = body.replace('</body>', `${liveReloadScript}</body>`);
+        }
+        originalSend.call(this, body);
+      };
+    }
+    next();
+  });
+
+  // Serve static files from the output directory
+  // This middleware needs to be dynamic if outputDir changes
+  let staticMiddleware = express.static(paths.outputDir);
+  app.use((req, res, next) => staticMiddleware(req, res, next));
+
+  // Initial build
+  console.log('🚀 Performing initial build for dev server...');
+  try {
+    await buildSite(configPathOption, { isDev: true }); // Use the original config path option
+    console.log('✅ Initial build complete.');
+  } catch (error) {
+      console.error('❌ Initial build failed:', error.message, error.stack);
+      // Optionally, don't start server if initial build fails, or serve a specific error page.
+  }
+
+
+  // Watch for changes
+  const watchedPaths = [
+    paths.srcDirToWatch,
+    paths.configFileToWatch,
+    DOCMD_TEMPLATES_DIR,
+    DOCMD_ASSETS_DIR
+  ];
+
+  console.log(`👀 Watching for changes in:
+    - Source: ${paths.srcDirToWatch}
+    - Config: ${paths.configFileToWatch}
+    - docmd Templates: ${DOCMD_TEMPLATES_DIR} (internal)
+    - docmd Assets: ${DOCMD_ASSETS_DIR} (internal)
+  `);
+
+  const watcher = chokidar.watch(watchedPaths, {
+    ignored: /(^|[\/\\])\../, // ignore dotfiles
+    persistent: true,
+    ignoreInitial: true, // Don't trigger for initial scan
+    awaitWriteFinish: { // Helps with rapid saves or large file writes
+        stabilityThreshold: 100,
+        pollInterval: 100
+    }
+  });
+
+  watcher.on('all', async (event, filePath) => {
+    const relativeFilePath = path.relative(CWD, filePath);
+    console.log(`🔄 Detected ${event} in ${relativeFilePath}. Rebuilding...`);
+    try {
+      if (filePath === paths.configFileToWatch) {
+        console.log('Config file changed. Reloading configuration...');
+        config = await loadConfig(configPathOption); // Reload config
+        const newPaths = resolveConfigPaths(config);
+
+        // Update watcher if srcDir changed - Chokidar doesn't easily support dynamic path changes after init.
+        // For simplicity, we might need to restart the watcher or inform user to restart dev server if srcDir/outputDir change.
+        // For now, we'll at least update the static server path.
+        if (newPaths.outputDir !== paths.outputDir) {
+            console.log(`Output directory changed from ${paths.outputDir} to ${newPaths.outputDir}. Updating static server.`);
+            staticMiddleware = express.static(newPaths.outputDir);
+        }
+        // If srcDirToWatch changes, chokidar won't automatically pick it up.
+        // A full dev server restart would be more robust for such config changes.
+        // For now, the old srcDir will still be watched.
+        paths = newPaths; // Update paths for next build reference
+      }
+
+      await buildSite(configPathOption, { isDev: true }); // Re-build using the potentially updated config path
+      broadcastReload();
+      console.log('✅ Rebuild complete. Browser should refresh.');
+    } catch (error) {
+      console.error('❌ Rebuild failed:', error.message, error.stack);
+    }
+  });
+
+  watcher.on('error', error => console.error(`Watcher error: ${error}`));
+
+  const PORT = process.env.PORT || 3000;
+  server.listen(PORT, async () => {
+    // Check if index.html exists after initial build
+    const indexHtmlPath = path.join(paths.outputDir, 'index.html');
+    if (!await fs.pathExists(indexHtmlPath)) {
+        console.warn(`⚠️  Warning: ${indexHtmlPath} not found after initial build.
+        The dev server is running, but you might see a 404 for the root page.
+        Ensure your '${config.srcDir}' directory contains an 'index.md' or your navigation points to existing files.`);
+    }
+    console.log(`🎉 Dev server started at http://localhost:${PORT}`);
+    console.log(`Serving content from: ${paths.outputDir}`);
+  });
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n🛑 Shutting down dev server...');
+    watcher.close();
+    wss.close(() => {
+        server.close(() => {
+            console.log('Server closed.');
+            process.exit(0);
+        });
+    });
+  });
+}
+
+module.exports = { startDevServer };

package/src/commands/init.js

@@ -0,0 +1,51 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+const defaultConfigContent = `// config.js
+module.exports = {
+  siteTitle: 'My Awesome Project Docs',
+  srcDir: 'docs',
+  outputDir: 'site',
+  theme: {
+    defaultMode: 'light', // 'light' or 'dark'
+  },
+  navigation: [
+    { title: 'Home', path: '/' }, // Corresponds to docs/index.md
+    // {
+    //   title: 'Category',
+    //   children: [
+    //     { title: 'Page 1', path: '/category/page1' },
+    //   ],
+    // },
+  ],
+};
+`;
+
+const defaultIndexMdContent = `---
+title: "Welcome"
+description: "Your documentation starts here."
+---
+
+# Hello, docmd!
+
+Start writing your Markdown content here.
+`;
+
+async function initProject() {
+  const baseDir = process.cwd();
+  const docsDir = path.join(baseDir, 'docs');
+  const configFile = path.join(baseDir, 'config.js');
+  const indexMdFile = path.join(docsDir, 'index.md');
+
+  if (await fs.pathExists(configFile) || await fs.pathExists(docsDir)) {
+    console.warn('⚠️  `docs/` directory or `config.js` already exists. Skipping creation to avoid overwriting.');
+  } else {
+    await fs.ensureDir(docsDir);
+    await fs.writeFile(configFile, defaultConfigContent, 'utf8');
+    await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8');
+    console.log('📄 Created `config.js`');
+    console.log('📁 Created `docs/` directory with a sample `index.md`');
+  }
+}
+
+module.exports = { initProject };

package/src/core/config-loader.js

@@ -0,0 +1,28 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+async function loadConfig(configPath) {
+  const absoluteConfigPath = path.resolve(process.cwd(), configPath);
+  if (!await fs.pathExists(absoluteConfigPath)) {
+    throw new Error(`Configuration file not found: ${absoluteConfigPath}`);
+  }
+  try {
+    // Clear require cache to always get the freshest config
+    delete require.cache[require.resolve(absoluteConfigPath)];
+    const config = require(absoluteConfigPath);
+
+    // Basic validation and defaults
+    if (!config.siteTitle) throw new Error('`siteTitle` is missing in config.js');
+    config.srcDir = config.srcDir || 'docs';
+    config.outputDir = config.outputDir || 'site';
+    config.theme = config.theme || {};
+    config.theme.defaultMode = config.theme.defaultMode || 'light';
+    config.navigation = config.navigation || [{ title: 'Home', path: '/' }];
+
+    return config;
+  } catch (e) {
+    throw new Error(`Error loading or parsing config file ${absoluteConfigPath}: ${e.message}`);
+  }
+}
+
+module.exports = { loadConfig };