@mgks/docmd 0.2.3 → 0.2.5

package/README.md

@@ -17,6 +17,8 @@
 
 Docmd (`docmd`) is a Node.js command-line tool dedicated to generating beautiful, lightweight static documentation sites from standard Markdown files. It champions the philosophy of "zero clutter, just content," prioritizing ease of use for documentation authors and a clean, performant experience for readers.
 
+#### 🟢 [Live Preview](https://docmd.mgks.dev): Documentation site powered entirely by *Docmd*, serving as both the official docs and a live demo.
+
 ## Features
 
 - 📝 **Markdown First** - Standard Markdown with YAML frontmatter
@@ -27,7 +29,7 @@ Docmd (`docmd`) is a Node.js command-line tool dedicated to generating beautiful
 - 🎭 **No-Style Pages** - Create custom standalone pages with complete HTML control
 - 🖌️ **Custom Styling** - Add custom CSS/JS and HTML directly in frontmatter
 - 💻 **Simple CLI** - Easy `init`, `dev`, and `build` commands
-- 🌐 **Deploy Anywhere** - Deploy the generated sites anywhere (GitHub Pages, Netlify, Vercel, etc.).
+- 🌐 **Deploy Anywhere** - Deploy the generated sites anywhere (GitHub Pages, Netlify, Vercel, etc.)
 
 ## Installation
 
@@ -80,4 +82,4 @@ If you find `docmd` useful, please consider:
 - Sharing it with others who might benefit
 - Reporting issues or submitting pull requests
 
-**[GitHub Sponsors](https://github.com/sponsors/mgks): Become a monthly or one-time GitHub sponsor to support docmd & other projects developed by [me](https://mgks.dev).**
+**[GitHub Sponsors](https://github.com/sponsors/mgks): Become a monthly or one-time GitHub sponsor to support docmd & other projects developed by [@mgks](https://mgks.dev).**

package/assets/css/welcome.css

@@ -1,6 +1,6 @@
 /*
  * Source file from the docmd project — https://github.com/mgks/docmd
- * Configuration for the docmd project's own documentation
+ * Welcome page stylesheet for the docmd project's own documentation
  */
 
 :root,html[data-theme=light]{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea}.theme-toggle,body{color:var(--text-color);display:flex}.logo-text,h1{font-weight:700}.install-code pre,.logo-text{font-family:'PT Mono',monospace}:root{--shadow-color:#00000014;--container-padding:5rem}@media (prefers-color-scheme:dark){:root{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#0000004d}}[data-theme=light]{--shadow-color:#00000059}[data-theme=dark]{--primary-color:#1955b6;--primary-hover:#084dbd;--text-color:#e0e0e0;--text-light:#aaa;--bg-color:#121212;--bg-secondary:#1e1e1e;--border-color:#333;--shadow-color:#000000de}*{margin:0;padding:0;box-sizing:border-box}body{font-family:Inter,-apple-system,BlinkMacSystemFont,sans-serif;line-height:1.5;background-color:var(--bg-color);height:100vh;overflow:hidden}.landing-container{display:flex;width:100%;height:100%;padding:0 var(--container-padding);max-width:1600px;margin:0 auto}.content-side{flex:1;padding:3rem 2rem 3rem 0;display:flex;flex-direction:column;justify-content:center}.preview-side{flex:1;display:flex;align-items:center;justify-content:flex-start;position:relative;overflow:visible}.header-top{position:absolute;top:2rem;right:3rem;z-index:100}.theme-toggle{background:var(--bg-secondary);border:1px solid var(--border-color);width:40px;height:40px;border-radius:50%;align-items:center;justify-content:center;cursor:pointer;transition:.2s}.theme-toggle:hover{background:var(--border-color)}.logo{margin-bottom:1.5rem;display:flex;align-items:center}.buttons,.features,.install-section,.tagline{margin-bottom:2rem}.logo svg{height:48px;width:auto}.logo-text{font-size:2em;margin-left:.25em}h1{font-size:3rem;margin-bottom:1rem;letter-spacing:-.02em}.tagline{font-size:1.25rem;color:var(--text-light);font-weight:400}.btn-primary,.feature-icon{background-color:var(--primary-color);color:#fff}.features{display:grid;grid-template-columns:repeat(2,1fr);gap:1.5rem}.feature{display:flex;align-items:flex-start;gap:.75rem}.feature-icon{width:32px;height:32px;border-radius:6px;display:flex;align-items:center;justify-content:center;flex-shrink:0}.feature-text{font-size:.9rem}.feature-text strong{display:block;margin-bottom:.25rem}.buttons{display:flex;gap:1rem}.btn{display:inline-flex;align-items:center;gap:.5rem;padding:.75rem 1.5rem;border-radius:8px;font-weight:600;font-size:1rem;text-decoration:none;transition:.2s}.btn-primary{border:none}.btn-secondary,.install-code pre{background-color:var(--bg-secondary);border:1px solid var(--border-color)}.btn-primary:hover{background-color:var(--primary-hover)}.btn-secondary{color:var(--text-color)}.btn-secondary:hover{background-color:var(--border-color)}.social-links{display:flex;gap:1rem;padding:0 .25em}.social-link{color:var(--text-light);transition:color .2s}.social-link:hover{color:var(--primary-color)}.preview-stack{position:relative;width:100%;height:400px;transform:translateX(15%);perspective:1000px}.preview-image{position:absolute;width:100%;max-width:700px;height:400px;border-radius:20px;box-shadow:0 25px 50px -12px var(--shadow-color);transition:.3s;overflow:hidden}.preview-image img{width:100%;height:100%;object-fit:cover;object-position:left top;border-radius:8px;pointer-events:none}.preview-image.top{z-index:3;transform:rotate(3deg) translateY(-10%) translateX(7%)}.preview-image.middle{z-index:2;transform:rotate(-3deg) translateY(1%) translateX(-2%)}.preview-image.bottom{z-index:1;transform:rotate(-8deg) translateY(10%) translateX(-10%)}[data-theme=dark] .preview-image .dark-img,[data-theme=light] .preview-image .light-img{display:block}[data-theme=dark] .preview-image .light-img,[data-theme=light] .preview-image .dark-img{display:none}@media (max-width:1400px){:root{--container-padding:3rem}.preview-stack{transform:translateX(15%)}}@media (max-width:1200px){:root{--container-padding:2rem}.preview-side{display:none}.content-side{max-width:100%;padding:3rem 0}.header-top{right:2rem}}@media (max-width:768px){:root{--container-padding:1.5rem}body{overflow:auto}.content-side{padding:2rem 0}.features{grid-template-columns:1fr}.buttons{flex-direction:column}.header-top{padding:1rem 0;text-align:center;right:1rem}h1{font-size:2.5rem}.tagline{font-size:1em;font-weight:500}.landing-container{padding:1rem;flex-direction:column}}.social-links .lucide-heart-handshake{color:#cd2727}.install-code{position:relative;display:inline-block}.install-code pre{border-radius:8px;padding:1rem 3.5rem 1rem 1rem;margin:0;font-size:.9rem;color:var(--text-color)}.install-code code{background:0 0;padding:0;color:inherit}.copy-button{position:absolute;top:.5rem;right:.5rem;background:var(--bg-color);border:1px solid var(--border-color);border-radius:4px;padding:.5rem;cursor:pointer;transition:.2s;color:var(--text-light)}.copy-button:hover{background:var(--border-color);color:var(--text-color)}

package/bin/docmd.js

@@ -1,11 +1,28 @@
 #!/usr/bin/env node
 
 const { Command } = require('commander');
+const fs = require('fs-extra');
+const path = require('path');
 const { version } = require('../package.json');
 const { initProject } = require('../src/commands/init');
 const { buildSite } = require('../src/commands/build');
 const { startDevServer } = require('../src/commands/dev');
 
+// Helper function to find the config file
+const findConfigFile = () => {
+  const newConfigPath = 'docmd.config.js';
+  const oldConfigPath = 'config.js';
+
+  if (fs.existsSync(path.resolve(process.cwd(), newConfigPath))) {
+    return newConfigPath;
+  }
+  if (fs.existsSync(path.resolve(process.cwd(), oldConfigPath))) {
+    return oldConfigPath;
+  }
+  
+  throw new Error('Configuration file not found. Please create a docmd.config.js file or run "docmd init".');
+};
+
 const program = new Command();
 
 program
@@ -15,7 +32,7 @@ program
 
 program
   .command('init')
-  .description('Initialize a new docmd project (creates docs/ and config.js)')
+  .description('Initialize a new docmd project (creates docs/ and config file)')
   .action(async () => {
     try {
       await initProject();
@@ -28,17 +45,27 @@ program
 
 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')
+  .description('Build the static site from Markdown files and config')
+  .option('-c, --config <path>', 'Path to config file')
   .option('-p, --preserve', 'Preserve existing asset files instead of updating them')
   .option('--no-preserve', 'Force update all asset files, overwriting existing ones')
+  .option('--silent', 'Suppress log output')
   .action(async (options) => {
     try {
-      console.log('🚀 Starting build process...');
-      await buildSite(options.config, { 
+      const originalLog = console.log;
+      if (options.silent) { console.log = () => {}; }
+
+      const configPath = options.config || findConfigFile();
+      console.log(`🚀 Starting build process using ${configPath}...`);
+      await buildSite(configPath, { 
         preserve: options.preserve
       });
-      console.log('✅ Build complete! Site generated in `site/` directory.');
+
+      console.log = originalLog;
+      if (!options.silent) {
+        console.log('✅ Build complete! Site generated in `site/` directory.');
+      }
+
     } catch (error) {
       console.error('❌ Build failed:', error.message);
       console.error(error.stack);
@@ -49,12 +76,24 @@ program
 program
   .command('dev')
   .description('Start a live preview development server')
-  .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--port <number>', 'Specify a port for the dev server')
   .option('-p, --preserve', 'Preserve existing asset files instead of updating them')
   .option('--no-preserve', 'Force update all asset files, overwriting existing ones')
+  .option('--silent', 'Suppress log output')
   .action(async (options) => {
     try {
-      await startDevServer(options.config, { preserve: options.preserve });
+      if (options.silent) {
+        const originalLog = console.log;
+        console.log = (message) => {
+          if (message && message.includes('Dev server started at')) {
+            originalLog(message);
+          }
+        };
+      }
+      const configPath = options.config || findConfigFile();
+      await startDevServer(configPath, { preserve: options.preserve, port: options.port });
+
     } catch (error) {
       console.error('❌ Dev server failed:', error.message);
       console.error(error.stack);

package/config.js

@@ -112,6 +112,7 @@ module.exports = {
           { title: 'Frontmatter', path: '/content/frontmatter', icon: 'file-text' },
           { title: 'Markdown Syntax', path: '/content/markdown-syntax', icon: 'code-2' },
           { title: 'Images', path: '/content/images', icon: 'image' },
+          { title: 'Mermaid Diagrams', path: '/content/mermaid', icon: 'network' },
           {
             title: 'Custom Containers',
             path: '/content/containers/',
@@ -163,6 +164,8 @@ module.exports = {
       { title: 'Issues', path: 'https://github.com/mgks/docmd/issues', icon: 'badge-alert', external: true }
   ],
 
+  pageNavigation: true, // Enable previous / next page navigation at the bottom of each page
+
   // Sponsor Ribbon Configuration
   sponsor: {
     enabled: true,                    // Enable/disable the sponsor ribbon

package/docs/cli-commands.md

@@ -20,9 +20,9 @@ docmd init
 This command creates the basic file and directory structure required for a `docmd` project:
 *   `docs/`: A directory to store your Markdown source files.
     *   `docs/index.md`: A sample Markdown file.
-*   `config.js`: The main configuration file for your site, pre-filled with default settings.
+*   `docmd.config.js`: The main configuration file for your site, pre-filled with default settings.
 
-If a `docs/` directory or `config.js` file already exists, `docmd init` will typically warn you and avoid overwriting them to prevent accidental data loss.
+If a `docs/` directory or `docmd.config.js` file already exists, `docmd init` will typically warn you and avoid overwriting them to prevent accidental data loss.
 
 **Options:**
 This command currently does not take any options.
@@ -37,7 +37,7 @@ docmd build [options]
 ```
 
 **Description:**
-The `build` command reads your Markdown files from the source directory (specified by `srcDir` in `config.js`, defaults to `docs/`), processes them along with your `config.js`, and generates a complete static website in the output directory (specified by `outputDir` in `config.js`, defaults to `site/`).
+The `build` command reads your Markdown files from the source directory (specified by `srcDir` in `docmd.config.js`, defaults to `docs/`), processes them along with your `docmd.config.js`, and generates a complete static website in the output directory (specified by `outputDir` in `docmd.config.js`, defaults to `site/`).
 
 The output `site/` directory contains all the HTML, CSS, JavaScript, and other assets needed to deploy your documentation.
 
@@ -46,14 +46,16 @@ By default, the build process will update all assets to ensure you have the late
 **Options:**
 
 *   `-c, --config <path>`
-    *   **Default:** `config.js`
-    *   **Description:** Specifies the path to the configuration file. Useful if your config file is not named `config.js` or is not in the project root.
-    *   **Example:** `docmd build --config my.docmd.config.js`
+    *   **Default:** `docmd.config.js` or `config.js`
+    *   **Description:** Specifies the path to the configuration file.
 
 *   `-p, --preserve`
     *   **Default:** `false`
-    *   **Description:** Preserves existing asset files instead of updating them. Use this flag if you've customized any of the default assets and want to keep your modifications.
-    *   **Example:** `docmd build --preserve`
+    *   **Description:** Preserves existing asset files instead of updating them.
+
+*   `--silent`
+    *   **Default:** `false`
+    *   **Description:** Suppresses most log output in the console. Useful for running in automated environments.
 
 ## `docmd dev`
 
@@ -68,7 +70,7 @@ docmd dev [options]
 The `dev` command is essential for writing and previewing your documentation. It:
 1.  Performs an initial build of your site.
 2.  Starts a local web server (usually on `http://localhost:3000`).
-3.  Watches your source files (`docs/` directory, `config.js`, and internal `docmd` theme assets) for changes.
+3.  Watches your source files (`docs/` directory, `docmd.config.js`, and internal `docmd` theme assets) for changes.
 4.  When a change is detected, it automatically rebuilds the necessary parts of your site and triggers a live reload in your browser.
 
 This provides a fast feedback loop, allowing you to see your changes almost instantly.
@@ -76,14 +78,21 @@ This provides a fast feedback loop, allowing you to see your changes almost inst
 **Options:**
 
 *   `-c, --config <path>`
-    *   **Default:** `config.js`
+    *   **Default:** `docmd.config.js` or `config.js`
     *   **Description:** Specifies the path to the configuration file.
-    *   **Example:** `docmd dev --config my.docmd.config.js`
+
+*   `--port <number>`
+    *   **Default:** `3000`
+    *   **Description:** Specifies the port for the development server. If the port is in use, docmd will automatically try the next available one.
+    *   **Example:** `docmd dev --port 8080`
 
 *   `-p, --preserve`
     *   **Default:** `false`
-    *   **Description:** Preserves existing asset files instead of updating them. Use this flag if you've customized any of the default assets and want to keep your modifications.
-    *   **Example:** `docmd dev --preserve`
+    *   **Description:** Preserves existing asset files instead of updating them.
+
+*   `--silent`
+    *   **Default:** `false`
+    *   **Description:** Suppresses most log output in the console. Useful for running in automated environments.
 
 **Note:** The development server starts on port 3000 by default. If port 3000 is already in use, the server will automatically try the next available port (3001, 3002, etc.) until it finds an open port.
 

package/docs/configuration.md

@@ -1,16 +1,15 @@
 ---
 title: "Configuration"
-description: "Detailed explanation of all options available in the docmd config.js file, including logo, theming, plugins, and more."
+description: "Detailed explanation of all options available in the docmd config file, including logo, theming, plugins, and more."
 ---
 
-# Configuration (`config.js`)
+# Configuration (`docmd.config.js`)
 
-`docmd` uses a `config.js` file in the root of your documentation project to control various aspects of your site. This file should export a JavaScript object containing your configuration options.
+`docmd` uses a `docmd.config.js` file in the root of your project... For backward compatibility, it will fall back to using `config.js` if `docmd.config.js` is not found.
 
-## Example `config.js` Structure:
+## Example `docmd.config.js` Structure:
 
 ```javascript
-// config.js
 module.exports = {
   siteTitle: 'My Awesome Project Docs',
   logo: {

package/docs/content/containers/buttons.md

@@ -16,9 +16,9 @@ The button container is a self-contained component. You provide its text, URL, a
 :::
 
 **Syntax:**
-```markdown
-::: button Button_Text /path/to/link [color:#hexcode]
-::: button Button_Text external:/external-url [color:#hexcode]
+```bash
+::: button Button_Text /path/to/link color:#hexcode
+::: button Button_Text external:/external-url color:#hexcode
 ```
 
 -   **`Button_Text`**: The text to display on the button. Use underscores (`_`) for spaces.
@@ -35,7 +35,7 @@ The button container is a self-contained component. You provide its text, URL, a
 This button will use the default theme color and link to a section on the current page.
 
 **Code:**
-```markdown
+```bash
 ::: button View_Examples #examples
 ```
 
@@ -47,7 +47,7 @@ This button will use the default theme color and link to a section on the curren
 External links open in a new tab for better user experience.
 
 **Code:**
-```markdown
+```bash
 ::: button GitHub_Repository external:https://github.com/mgks/docmd
 ```
 
@@ -59,7 +59,7 @@ External links open in a new tab for better user experience.
 You can easily override the color for emphasis.
 
 **Code:**
-```markdown
+```bash
 ::: button Getting_Started #getting-started color:#28a745
 ```
 
@@ -72,7 +72,7 @@ Buttons are flexible and can be placed inside other containers, like cards or ca
 
 **Code:**
 
-```markdown
+```bash
 ::: card Feature Announcement
 Our latest feature is now available! Read the full documentation to learn more about how it works.
 ::: button Read_More /path/to/feature/docs/

package/docs/content/frontmatter.md

@@ -52,6 +52,14 @@ Examples of custom fields you *might* add (these are not built-in features):
 *   `tags`: ["tag1", "tag2"]
 *   `permalink`: "https://example.com/your-canonical-url/" (Sets the canonical URL for SEO purposes)
 
+## Page-Specific Behavior Fields
+
+*   **`toc`** (Boolean, Optional)
+    *   **Purpose:** Controls the visibility of the "On This Page" table of contents sidebar.
+    *   **Default:** `true` (TOC is visible if the page has headings).
+    *   **Usage:** Set to `false` to completely hide the TOC sidebar for a specific page. This is useful for landing pages or pages with minimal content.
+    *   **Example:** `toc: false`
+
 ## Example Usage
 
 Consider a file named `docs/guides/installation.md`:

package/docs/content/index.md

@@ -12,6 +12,7 @@ docmd uses Markdown files to create beautiful documentation. This section covers
 - [**Frontmatter**](/content/frontmatter/) - Learn how to add metadata to your pages
 - [**Markdown Syntax**](/content/markdown-syntax/) - Basic and advanced Markdown features
 - [**Images**](/content/images/) - How to add and style images in your documentation
+- [**Mermaid Diagrams**](/content/mermaid/) - Create beautiful diagrams and flowcharts with Mermaid
 - [**Custom Containers**](/content/custom-containers/) - Special content blocks like callouts and cards
 - [**noStyle Pages**](/content/no-style-pages/) - Create custom standalone pages with complete HTML control