@mgks/docmd 0.1.1 → 0.1.2

package/.github/workflows/publish.yml

@@ -2,7 +2,7 @@ name: Publish Package to NPM and GitHub Packages
 
 on:
   release:
-    types: [created, published] # Triggers when a new GitHub Release is created or published
+    types: [created] # [created, published] Triggers when a new GitHub Release is created or published
   workflow_dispatch: # Allows manual triggering for testing
 
 jobs:

package/bin/docmd.js

@@ -30,7 +30,8 @@ program
   .command('build')
   .description('Build the static site from Markdown files and config.js')
   .option('-c, --config <path>', 'Path to config.js file', 'config.js')
-  .option('-p, --preserve', 'Preserve existing asset files instead of updating them', false)
+  .option('-p, --preserve', 'Preserve existing asset files instead of updating them')
+  .option('--no-preserve', 'Force update all asset files, overwriting existing ones')
   .action(async (options) => {
     try {
       console.log('🚀 Starting build process...');
@@ -49,7 +50,8 @@ program
   .command('dev')
   .description('Start a live preview development server')
   .option('-c, --config <path>', 'Path to config.js file', 'config.js')
-  .option('-p, --preserve', 'Preserve existing asset files instead of updating them', false)
+  .option('-p, --preserve', 'Preserve existing asset files instead of updating them')
+  .option('--no-preserve', 'Force update all asset files, overwriting existing ones')
   .action(async (options) => {
     try {
       await startDevServer(options.config, { preserve: options.preserve });

package/docs/theming/assets-management.md

@@ -0,0 +1,126 @@
+---
+title: "Assets Management"
+description: "Learn how to manage and customize your assets (CSS, JavaScript, images) in your docmd site."
+---
+
+# Assets Management
+
+Managing your custom assets (CSS, JavaScript, images) is an important part of customizing your documentation site. `docmd` provides flexible ways to include and manage these assets.
+
+## Project Structure
+
+When you initialize a new project with `docmd init`, it creates the following structure:
+
+```
+your-project/
+├── assets/           # User assets directory
+│   ├── css/          # Custom CSS files
+│   ├── js/           # Custom JavaScript files
+│   └── images/       # Custom images
+├── docs/             # Markdown content
+├── config.js
+└── ...
+```
+
+This structure makes it easy to organize and manage your custom assets.
+
+## How Assets Are Handled
+
+There are two main ways to manage assets in your docmd site:
+
+### 1. Root-Level Assets Directory (Recommended)
+
+The simplest and recommended approach is to use the `assets/` directory in your project root:
+
+**How it works:**
+- During the build process, docmd automatically copies everything from your root `assets/` directory to the output `site/assets/` directory
+- Your custom assets take precedence over docmd's built-in assets with the same name
+- This approach is ideal for GitHub Pages deployments and other hosting scenarios
+
+**Example workflow:**
+1. Create or modify files in your project's `assets/` directory:
+   ```
+   assets/css/custom-styles.css
+   assets/js/interactive-features.js
+   assets/images/logo.png
+   ```
+
+2. Reference these files in your `config.js`:
+   ```javascript
+   module.exports = {
+     // ...
+     theme: {
+       // ...
+       customCss: [
+         '/assets/css/custom-styles.css',
+       ],
+     },
+     customJs: [
+       '/assets/js/interactive-features.js',
+     ],
+     // ...
+   };
+   ```
+
+3. Use images in your Markdown content:
+   ```markdown
+   ![Logo](/assets/images/logo.png)
+   ```
+
+4. Build your site:
+   ```bash
+   docmd build
+   ```
+
+### 2. Customizing Default Assets
+
+If you want to modify docmd's default assets:
+
+1. First, build your site normally to generate all assets:
+   ```bash
+   docmd build
+   ```
+
+2. Modify the generated files in the `site/assets` directory as needed.
+
+3. When rebuilding, use the `--preserve` flag to keep your customized files:
+   ```bash
+   docmd build --preserve
+   ```
+
+4. If you want to update to the latest docmd assets (for example, after updating the package), run without the preserve flag:
+   ```bash
+   docmd build
+   ```
+
+This approach allows you to:
+- Get the latest assets by default when you update the package
+- Preserve your customizations when needed with `--preserve`
+- See which files are being preserved during the build process
+
+The preservation behavior works with both `build` and `dev` commands:
+```bash
+# Preserve custom assets during development
+docmd dev --preserve
+```
+
+## Asset Precedence
+
+When multiple assets with the same name exist, docmd follows this precedence order:
+
+1. **User assets** from the root `assets/` directory (highest priority)
+2. **Preserved assets** from previous builds (if `--preserve` is enabled, which is the default)
+3. **Built-in assets** from the docmd package (lowest priority)
+
+This ensures your custom assets always take precedence over default ones.
+
+## GitHub Pages Deployment
+
+When deploying to GitHub Pages, your assets structure is preserved. If you're using a custom domain or GitHub Pages URL, make sure your asset paths are correctly configured.
+
+For more information on deployment, see the [Deployment](/deployment/) documentation.
+
+## Related Topics
+
+- [Custom CSS & JS](/theming/custom-css-js/) - Learn how to configure custom CSS and JavaScript
+- [Theming](/theming/) - Explore other theming options for your documentation site 

package/docs/theming/custom-css-js.md

@@ -1,5 +1,5 @@
 ---
-title: "Custom CSS & JS"
+title: "Custom Styles & Scripts"
 description: "Learn how to add your own custom CSS and JavaScript to your docmd site for advanced customization."
 ---
 
@@ -30,41 +30,8 @@ module.exports = {
 **How it works:**
 *   Each string in the `customCss` array should be an absolute path from the root of your generated `site/` directory (e.g., if your file is `site/assets/css/my-branding.css`, the path is `/assets/css/my-branding.css`).
 *   These `<link rel="stylesheet">` tags will be added to the `<head>` of every page *after* the main theme CSS and `highlight.js` CSS. This allows your custom styles to override the default theme styles.
-*   You are responsible for ensuring these CSS files exist at the specified locations in your final `site/` output. Typically, you would:
-    1.  Create your custom CSS files (e.g., `my-branding.css`).
-    2.  Place them in a folder within your project (e.g., `my-project/static-assets/css/`).
-    3.  Ensure that this folder (or its contents) is copied to the correct location in your `site/` directory during `docmd`'s asset copying process. If `docmd` copies a top-level `assets/` folder from your source, place them there.
 
-## Managing Custom Assets
-
-By default, `docmd` will always update assets to the latest version when you run `build` or `dev` commands. This ensures your site benefits from the latest improvements and fixes.
-
-### Customizing Default Assets
-
-If you want to customize default assets (like theme CSS files or scripts):
-
-1. First, build your site normally to generate all assets:
-   ```bash
-   docmd build
-   ```
-
-2. Modify the generated files in the `site/assets` directory as needed.
-
-3. When rebuilding, use the `--preserve` flag to keep your customized files:
-   ```bash
-   docmd build --preserve
-   ```
-
-This approach allows you to:
-- Always get the latest assets when you want them (default behavior)
-- Preserve your customizations when needed (with `--preserve`)
-- Easily see which files are being preserved during the build process
-
-The `--preserve` flag works with both `build` and `dev` commands:
-```bash
-# Preserve custom assets during development
-docmd dev --preserve
-```
+> **Note:** For information on how to manage your custom asset files (CSS, JS, images), see the [Assets Management](/theming/assets-management/) documentation.
 
 **Use Cases for Custom CSS:**
 *   **Overriding CSS Variables:** The `default` theme uses CSS variables extensively. You can redefine these in your custom CSS.
@@ -104,7 +71,6 @@ module.exports = {
 **How it works:**
 *   Each string in the `customJs` array should be an absolute path from the root of your generated `site/` directory.
 *   These `<script src="..."></script>` tags will be added just before the closing `</body>` tag on every page. This ensures the DOM is loaded before your scripts run and is generally better for page performance.
-*   Similar to custom CSS, you are responsible for ensuring these JavaScript files exist at the specified locations in your final `site/` output.
 
 **Use Cases for Custom JS:**
 *   Adding interactive elements (e.g., custom modals, tabs not provided by `docmd`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "bin": {
@@ -35,7 +35,6 @@
   },
   "homepage": "https://github.com/mgks/docmd#readme",
   "dependencies": {
-    "@mgks/docmd": "^0.1.0",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
     "ejs": "^3.1.9",

package/src/assets/css/docmd-main.css

@@ -506,8 +506,10 @@
     text-align: right;
     opacity: 0.9;
     font-weight: 500;
-
 }
+.branding-footer svg {
+  color: rgb(251, 58, 58);
+  }
 
   .page-footer a {
     color: var(--link-color);

package/src/commands/build.js

@@ -35,6 +35,7 @@ async function buildSite(configPath, options = { isDev: false, preserve: false }
   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}`);
@@ -57,6 +58,33 @@ async function buildSite(configPath, options = { isDev: false, preserve: false }
 
   // 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');
@@ -64,7 +92,7 @@ async function buildSite(configPath, options = { isDev: false, preserve: false }
   
   if (await fs.pathExists(assetsSrcDir)) {
     if (!options.isDev) {
-      console.log(`📂 Copying assets to ${assetsDestDir}...`);
+      console.log(`📂 Copying docmd assets to ${assetsDestDir}...`);
     }
     
     // Create destination directory if it doesn't exist
@@ -81,10 +109,13 @@ async function buildSite(configPath, options = { isDev: false, preserve: false }
       // Check if destination file already exists
       const fileExists = await fs.pathExists(destFile);
       
-      if (fileExists && options.preserve) {
+      // 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) {
+        if (!options.isDev && options.preserve) {
           console.log(`  Preserving existing file: ${relativePath}`);
         }
       } else {
@@ -327,7 +358,7 @@ async function buildSite(configPath, options = { isDev: false, preserve: 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}`);
     }
@@ -339,6 +370,16 @@ async function buildSite(configPath, options = { isDev: false, preserve: false }
     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

package/src/commands/dev.js

@@ -18,6 +18,7 @@ async function startDevServer(configPathOption, options = { preserve: false }) {
       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, options = { preserve: false }) {
         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, options = { preserve: false }) {
     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);
@@ -95,21 +163,38 @@ async function startDevServer(configPathOption, options = { preserve: false }) {
       // 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
@@ -145,7 +230,7 @@ async function startDevServer(configPathOption, options = { preserve: false }) {
 
       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, options = { preserve: false }) {
     }
     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,5 +1,6 @@
 const fs = require('fs-extra');
 const path = require('path');
+const readline = require('readline');
 
 const defaultConfigContent = `// config.js: basic config for docmd
 module.exports = {
@@ -76,9 +77,18 @@ module.exports = {
   // Icons are kebab-case names from Lucide Icons (https://lucide.dev/)
   navigation: [
       { 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 },
-      { title: 'Documentation', path: 'https://github.com/mgks/docmd', icon: 'scroll', external: true }
   ],
 
   // Footer Configuration
@@ -106,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/plugins/sitemap.js

@@ -6,11 +6,15 @@ const path = require('path');
  * @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
+ * @param {Object} options - Additional options
+ * @param {boolean} options.isDev - Whether running in development mode
  */
-async function generateSitemap(config, pages, outputDir) {
+async function generateSitemap(config, pages, outputDir, options = { isDev: false }) {
   // Skip if no siteUrl is defined (sitemap needs absolute URLs)
   if (!config.siteUrl) {
-    console.warn('⚠️ No siteUrl defined in config. Skipping sitemap generation.');
+    if (!options.isDev) {
+      console.warn('⚠️ No siteUrl defined in config. Skipping sitemap generation.');
+    }
     return;
   }
 
@@ -94,7 +98,10 @@ async function generateSitemap(config, pages, outputDir) {
   const sitemapPath = path.join(outputDir, 'sitemap.xml');
   await fs.writeFile(sitemapPath, sitemapXml);
   
-  console.log(`✅ Generated sitemap at ${sitemapPath}`);
+  // Only show sitemap generation message in production mode or if DOCMD_DEV is true
+  if (!options.isDev || process.env.DOCMD_DEV === 'true') {
+    console.log(`✅ Generated sitemap at ${sitemapPath}`);
+  }
 }
 
 module.exports = { generateSitemap }; 

package/src/templates/layout.ejs

@@ -100,7 +100,7 @@
                     <%- footerHtml || '' %>
                 </div>
                 <div class="branding-footer">
-                    Build with 💜 <a href="https://docmd.mgks.dev" target="_blank" rel="noopener">docmd.</a>
+                    Build with <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"></path><path d="M12 5 9.04 7.96a2.17 2.17 0 0 0 0 3.08c.82.82 2.13.85 3 .07l2.07-1.9a2.82 2.82 0 0 1 3.79 0l2.96 2.66"></path><path d="m18 15-2-2"></path><path d="m15 18-2-2"></path></svg> <a href="https://docmd.mgks.dev" target="_blank" rel="noopener">docmd.</a>
                 </div>
             </div>
         </footer>