@mgks/docmd 0.1.0 → 0.1.2

package/src/commands/build.js

@@ -6,6 +6,7 @@ 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
+const { version } = require('../../package.json'); // Import package version
 
 // Debug function to log navigation information
 function logNavigationPaths(pagePath, navPath, normalizedPath) {
@@ -17,37 +18,119 @@ function logNavigationPaths(pagePath, navPath, 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 }) {
+// Asset version metadata - update this when making significant changes to assets
+const ASSET_VERSIONS = {
+  'css/docmd-main.css': { version: version, description: 'Core styles' },
+  'css/docmd-theme-sky.css': { version: version, description: 'Sky theme' },
+  'css/docmd-highlight-light.css': { version: version, description: 'Light syntax highlighting' },
+  'css/docmd-highlight-dark.css': { version: version, description: 'Dark syntax highlighting' },
+  'js/docmd-theme-toggle.js': { version: version, description: 'Theme toggle functionality' },
+  // Add other assets here with their versions
+};
+
+async function buildSite(configPath, options = { isDev: false, preserve: 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);
+  const USER_ASSETS_DIR = path.resolve(CWD, 'assets'); // User's custom assets directory
 
   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}`);
+  // Create output directory if it doesn't exist
+  await fs.ensureDir(OUTPUT_DIR);
+
+  // Instead of emptying the entire directory, we'll selectively clean up HTML files
+  // This preserves custom assets while ensuring we don't have stale HTML files
+  if (await fs.pathExists(OUTPUT_DIR)) {
+    const cleanupFiles = await findFilesToCleanup(OUTPUT_DIR);
+    for (const file of cleanupFiles) {
+      await fs.remove(file);
+    }
+    if (!options.isDev) {
+      console.log(`🧹 Cleaned HTML files from output directory: ${OUTPUT_DIR}`);
+    }
+  }
+
+  // Track preserved files for summary report
+  const preservedFiles = [];
+  const userAssetsCopied = [];
+
+  // Copy user assets from root assets/ directory if it exists
+  if (await fs.pathExists(USER_ASSETS_DIR)) {
+    const assetsDestDir = path.join(OUTPUT_DIR, 'assets');
+    await fs.ensureDir(assetsDestDir);
+    
+    if (!options.isDev) {
+      console.log(`📂 Copying user assets from ${USER_ASSETS_DIR} to ${assetsDestDir}...`);
+    }
+    
+    const userAssetFiles = await getAllFiles(USER_ASSETS_DIR);
+    
+    for (const srcFile of userAssetFiles) {
+      const relativePath = path.relative(USER_ASSETS_DIR, srcFile);
+      const destFile = path.join(assetsDestDir, relativePath);
+      
+      // Ensure directory exists
+      await fs.ensureDir(path.dirname(destFile));
+      await fs.copyFile(srcFile, destFile);
+      userAssetsCopied.push(relativePath);
+    }
+    
+    if (!options.isDev && userAssetsCopied.length > 0) {
+      console.log(`📦 Copied ${userAssetsCopied.length} user assets`);
+    }
   }
 
+  // Copy assets
   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}`);
+      console.log(`📂 Copying docmd assets to ${assetsDestDir}...`);
+    }
+    
+    // Create destination directory if it doesn't exist
+    await fs.ensureDir(assetsDestDir);
+    
+    // Get all files from source directory recursively
+    const assetFiles = await getAllFiles(assetsSrcDir);
+    
+    // Copy each file individually, checking for existing files if preserve flag is set
+    for (const srcFile of assetFiles) {
+      const relativePath = path.relative(assetsSrcDir, srcFile);
+      const destFile = path.join(assetsDestDir, relativePath);
+      
+      // Check if destination file already exists
+      const fileExists = await fs.pathExists(destFile);
+      
+      // Skip if the file exists and either:
+      // 1. The preserve flag is set, OR
+      // 2. The file was copied from user assets (user assets take precedence)
+      if (fileExists && (options.preserve || userAssetsCopied.includes(relativePath))) {
+        // Skip file and add to preserved list
+        preservedFiles.push(relativePath);
+        if (!options.isDev && options.preserve) {
+          console.log(`  Preserving existing file: ${relativePath}`);
+        }
+      } else {
+        // Copy file (either it doesn't exist or we're not preserving)
+        await fs.ensureDir(path.dirname(destFile));
+        await fs.copyFile(srcFile, destFile);
+      }
     }
   } 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 lightThemePath = path.join(__dirname, '..', 'assets', 'css', 'docmd-highlight-light.css');
+  const darkThemePath = path.join(__dirname, '..', 'assets', 'css', 'docmd-highlight-dark.css');
 
   const themesMissing = !await fs.pathExists(lightThemePath) || !await fs.pathExists(darkThemePath);
 
@@ -275,11 +358,70 @@ async function buildSite(configPath, options = { isDev: false }) {
   // Generate sitemap if enabled in config
   if (config.plugins?.sitemap !== false) {
     try {
-      await generateSitemap(config, processedPages, OUTPUT_DIR);
+      await generateSitemap(config, processedPages, OUTPUT_DIR, { isDev: options.isDev });
     } catch (error) {
       console.error(`❌ Error generating sitemap: ${error.message}`);
     }
   }
+
+  // Print summary of preserved files at the end of build
+  if (preservedFiles.length > 0 && !options.isDev) {
+    console.log(`\n📋 Build Summary: ${preservedFiles.length} existing files were preserved:`);
+    preservedFiles.forEach(file => console.log(`  - assets/${file}`));
+    console.log(`\nTo update these files in future builds, run without the --preserve flag.`);
+  }
+  
+  if (userAssetsCopied.length > 0 && !options.isDev) {
+    console.log(`\n📋 User Assets: ${userAssetsCopied.length} files were copied from your assets/ directory:`);
+    if (userAssetsCopied.length <= 10) {
+      userAssetsCopied.forEach(file => console.log(`  - assets/${file}`));
+    } else {
+      userAssetsCopied.slice(0, 5).forEach(file => console.log(`  - assets/${file}`));
+      console.log(`  - ... and ${userAssetsCopied.length - 5} more files`);
+    }
+  }
+}
+
+// Helper function to find HTML files and sitemap.xml to clean up
+async function findFilesToCleanup(dir) {
+  const filesToRemove = [];
+  const items = await fs.readdir(dir, { withFileTypes: true });
+  
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    
+    if (item.isDirectory()) {
+      // Don't delete the assets directory
+      if (item.name !== 'assets') {
+        const subDirFiles = await findFilesToCleanup(fullPath);
+        filesToRemove.push(...subDirFiles);
+      }
+    } else if (
+      item.name.endsWith('.html') || 
+      item.name === 'sitemap.xml'
+    ) {
+      filesToRemove.push(fullPath);
+    }
+  }
+  
+  return filesToRemove;
+}
+
+// Helper function to recursively get all files in a directory
+async function getAllFiles(dir) {
+  const 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.push(...await getAllFiles(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  
+  return files;
 }
 
 // findMarkdownFiles function remains the same

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`
 
@@ -18,6 +18,7 @@ async function startDevServer(configPathOption) {
       outputDir: path.resolve(CWD, currentConfig.outputDir),
       srcDirToWatch: path.resolve(CWD, currentConfig.srcDir),
       configFileToWatch: path.resolve(CWD, configPathOption), // Path to the config file itself
+      userAssetsDir: path.resolve(CWD, 'assets'), // User's assets directory
     };
   };
 
@@ -65,11 +66,72 @@ async function startDevServer(configPathOption) {
         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'); };
+              (function() {
+                // More robust WebSocket connection with automatic reconnection
+                let socket;
+                let reconnectAttempts = 0;
+                const maxReconnectAttempts = 5;
+                const reconnectDelay = 1000; // Start with 1 second delay
+                
+                function connect() {
+                  socket = new WebSocket(\`ws://\${window.location.host}\`);
+                  
+                  socket.onmessage = function(event) { 
+                    if (event.data === 'reload') {
+                      console.log('Received reload signal. Refreshing page...');
+                      window.location.reload(); 
+                    }
+                  };
+                  
+                  socket.onopen = function() {
+                    console.log('Live reload connected.');
+                    reconnectAttempts = 0; // Reset reconnect counter on successful connection
+                  };
+                  
+                  socket.onclose = function() {
+                    if (reconnectAttempts < maxReconnectAttempts) {
+                      reconnectAttempts++;
+                      const delay = reconnectDelay * Math.pow(1.5, reconnectAttempts - 1); // Exponential backoff
+                      console.log(\`Live reload disconnected. Reconnecting in \${delay/1000} seconds...\`);
+                      setTimeout(connect, delay);
+                    } else {
+                      console.log('Live reload disconnected. Max reconnect attempts reached.');
+                    }
+                  };
+                  
+                  socket.onerror = function(error) {
+                    console.error('WebSocket error:', error);
+                  };
+                }
+                
+                // Initial connection
+                connect();
+                
+                // Backup reload mechanism using polling for browsers with WebSocket issues
+                let lastModified = new Date().getTime();
+                const pollInterval = 2000; // Poll every 2 seconds
+                
+                function checkForChanges() {
+                  fetch(window.location.href, { method: 'HEAD', cache: 'no-store' })
+                    .then(response => {
+                      const serverLastModified = new Date(response.headers.get('Last-Modified')).getTime();
+                      if (serverLastModified > lastModified) {
+                        console.log('Change detected via polling. Refreshing page...');
+                        window.location.reload();
+                      }
+                      lastModified = serverLastModified;
+                    })
+                    .catch(error => console.error('Error checking for changes:', error));
+                }
+                
+                // Only use polling as a fallback if WebSocket fails
+                setTimeout(() => {
+                  if (socket.readyState !== WebSocket.OPEN) {
+                    console.log('WebSocket not connected. Falling back to polling.');
+                    setInterval(checkForChanges, pollInterval);
+                  }
+                }, 5000);
+              })();
             </script>
           `;
           body = body.replace('</body>', `${liveReloadScript}</body>`);
@@ -80,6 +142,12 @@ async function startDevServer(configPathOption) {
     next();
   });
 
+  // Add Last-Modified header to all responses for polling fallback
+  app.use((req, res, next) => {
+    res.setHeader('Last-Modified', new Date().toUTCString());
+    next();
+  });
+
   // Serve static files from the output directory
   // This middleware needs to be dynamic if outputDir changes
   let staticMiddleware = express.static(paths.outputDir);
@@ -88,28 +156,45 @@ 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);
       // Optionally, don't start server if initial build fails, or serve a specific error page.
   }
 
+  // Check if user assets directory exists
+  const userAssetsDirExists = await fs.pathExists(paths.userAssetsDir);
 
   // 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)
-  `);
+  // Add user assets directory to watched paths if it exists
+  if (userAssetsDirExists) {
+    watchedPaths.push(paths.userAssetsDir);
+  }
+
+  // Add internal paths for docmd development (not shown to end users)
+  const internalPaths = [DOCMD_TEMPLATES_DIR, DOCMD_ASSETS_DIR];
+  
+  // Only in development environments, we might want to watch internal files too
+  if (process.env.DOCMD_DEV === 'true') {
+    watchedPaths.push(...internalPaths);
+  }
+
+  console.log(`👀 Watching for changes in:`);
+  console.log(`    - Source: ${paths.srcDirToWatch}`);
+  console.log(`    - Config: ${paths.configFileToWatch}`);
+  if (userAssetsDirExists) {
+    console.log(`    - Assets: ${paths.userAssetsDir}`);
+  }
+  if (process.env.DOCMD_DEV === 'true') {
+    console.log(`    - docmd Templates: ${DOCMD_TEMPLATES_DIR} (internal)`);
+    console.log(`    - docmd Assets: ${DOCMD_ASSETS_DIR} (internal)`);
+  }
 
   const watcher = chokidar.watch(watchedPaths, {
     ignored: /(^|[\/\\])\../, // ignore dotfiles
@@ -143,9 +228,9 @@ 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.');
+      console.log('✅ Rebuild complete. Browser will refresh automatically.');
     } catch (error) {
       console.error('❌ Rebuild failed:', error.message, error.stack);
     }
@@ -164,6 +249,7 @@ async function startDevServer(configPathOption) {
     }
     console.log(`🎉 Dev server started at http://localhost:${PORT}`);
     console.log(`Serving content from: ${paths.outputDir}`);
+    console.log(`Live reload is active. Browser will refresh automatically when files change.`);
   });
 
   // Graceful shutdown

package/src/commands/init.js

@@ -1,23 +1,103 @@
 const fs = require('fs-extra');
 const path = require('path');
+const readline = require('readline');
 
-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
+      {
+        title: 'Getting Started',
+        icon: 'rocket',
+        path: '#',
+        children: [
+          { title: 'Documentation', path: 'https://docmd.mgks.dev', icon: 'scroll', external: true },
+          { title: 'Installation', path: 'https://docmd.mgks.dev/getting-started/installation', icon: 'download', external: true },
+          { title: 'Basic Usage', path: 'https://docmd.mgks.dev/getting-started/basic-usage', icon: 'play', external: true },
+        ],
+      },
+      // External links:
+      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
   ],
+
+  // Footer Configuration
+  // Markdown is supported here.
+  footer: '© ' + new Date().getFullYear() + ' Project.',
+
+  // Favicon Configuration
+  // Path relative to outputDir root
+  favicon: '/assets/favicon.ico',
 };
 `;
 
@@ -36,16 +116,117 @@ async function initProject() {
   const docsDir = path.join(baseDir, 'docs');
   const configFile = path.join(baseDir, 'config.js');
   const indexMdFile = path.join(docsDir, 'index.md');
+  const assetsDir = path.join(baseDir, 'assets');
+  const assetsCssDir = path.join(assetsDir, 'css');
+  const assetsJsDir = path.join(assetsDir, 'js');
+  const assetsImagesDir = path.join(assetsDir, 'images');
+  
+  const existingFiles = [];
+  const dirExists = {
+    docs: false,
+    assets: false
+  };
+  
+  // Check each file individually
+  if (await fs.pathExists(configFile)) {
+    existingFiles.push('config.js');
+  }
+  
+  if (await fs.pathExists(docsDir)) {
+    dirExists.docs = true;
+    
+    if (await fs.pathExists(indexMdFile)) {
+      existingFiles.push('docs/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 {
+  // Check if assets directory exists
+  if (await fs.pathExists(assetsDir)) {
+    dirExists.assets = true;
+  }
+  
+  // Determine if we should override existing files
+  let shouldOverride = false;
+  if (existingFiles.length > 0) {
+    console.warn('⚠️  The following files already exist:');
+    existingFiles.forEach(file => console.warn(`   - ${file}`));
+    
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    
+    const answer = await new Promise(resolve => {
+      rl.question('Do you want to override these files? (y/N): ', resolve);
+    });
+    
+    rl.close();
+    
+    shouldOverride = answer.toLowerCase() === 'y';
+    
+    if (!shouldOverride) {
+      console.log('⏭️  Skipping existing files. Will only create new files.');
+    }
+  }
+  
+  // Create docs directory if it doesn't exist
+  if (!dirExists.docs) {
     await fs.ensureDir(docsDir);
+    console.log('📁 Created `docs/` directory');
+  } else {
+    console.log('📁 Using existing `docs/` directory');
+  }
+
+  // Create assets directory structure if it doesn't exist
+  if (!dirExists.assets) {
+    await fs.ensureDir(assetsDir);
+    await fs.ensureDir(assetsCssDir);
+    await fs.ensureDir(assetsJsDir);
+    await fs.ensureDir(assetsImagesDir);
+    console.log('📁 Created `assets/` directory with css, js, and images subdirectories');
+  } else {
+    console.log('📁 Using existing `assets/` directory');
+    
+    // Create subdirectories if they don't exist
+    if (!await fs.pathExists(assetsCssDir)) {
+      await fs.ensureDir(assetsCssDir);
+      console.log('📁 Created `assets/css/` directory');
+    }
+    
+    if (!await fs.pathExists(assetsJsDir)) {
+      await fs.ensureDir(assetsJsDir);
+      console.log('📁 Created `assets/js/` directory');
+    }
+    
+    if (!await fs.pathExists(assetsImagesDir)) {
+      await fs.ensureDir(assetsImagesDir);
+      console.log('📁 Created `assets/images/` directory');
+    }
+  }
+  
+  // Write config file if it doesn't exist or user confirmed override
+  if (!await fs.pathExists(configFile)) {
     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`');
+  } else if (shouldOverride) {
+    await fs.writeFile(configFile, defaultConfigContent, 'utf8');
+    console.log('📄 Updated `config.js`');
+  } else {
+    console.log('⏭️  Skipped existing `config.js`');
+  }
+  
+  // Write index.md file if it doesn't exist or user confirmed override
+  if (!await fs.pathExists(indexMdFile)) {
+    await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8');
+    console.log('📄 Created `docs/index.md`');
+  } else if (shouldOverride) {
+    await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8');
+    console.log('📄 Updated `docs/index.md`');
+  } else {
+    console.log('⏭️  Skipped existing `docs/index.md`');
   }
+  
+  console.log('✅ Project initialization complete!');
 }
 
 module.exports = { initProject };

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