@mgks/docmd 0.1.4 → 0.2.0

package/README.md

@@ -70,7 +70,7 @@ Contributions are welcome! Please check our [contributing guidelines](https://do
 
 ## License
 
-`docmd` is licensed under the [MIT License](LICENSE).
+`docmd` is licensed under the [MIT License](https://github.com/mgks/docmd/blob/main/LICENSE).
 
 ## Support the Project
 
@@ -80,6 +80,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).**
-
-<br /><img src="https://forthebadge.com/images/badges/built-with-love.svg" alt="Built with Love">
+**[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).**

package/assets/css/welcome.css

@@ -1,378 +1,66 @@
-:root {
-    --primary-color: #047bf1;
-    --primary-hover: #026ed9;
-    --text-color: #333;
-    --text-light: #666;
-    --bg-color: #fff;
-    --bg-secondary: #f8f9fa;
-    --border-color: #eaeaea;
-    --shadow-color: rgba(0, 0, 0, 0.08);
-    --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: rgba(0, 0, 0, 0.3);
-    }
-  }
-  
-  [data-theme="light"] {
-    --primary-color: #047bf1;
-    --primary-hover: #026ed9;
-    --text-color: #333;
-    --text-light: #666;
-    --bg-color: #fff;
-    --bg-secondary: #f8f9fa;
-    --border-color: #eaeaea;
-    --shadow-color: rgba(0, 0, 0, 0.35);
-
+:root{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea;--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="dark"] {
-    --primary-color: #1955b6;
-    --primary-hover: #084dbd;
-    --text-color: #e0e0e0;
-    --text-light: #aaa;
-    --bg-color: #121212;
-    --bg-secondary: #1e1e1e;
-    --border-color: #333;
-    --shadow-color: rgba(0, 0, 0, 0.87);
-
+[data-theme="light"]{--primary-color:#047bf1;--primary-hover:#026ed9;--text-color:#333;--text-light:#666;--bg-color:#fff;--bg-secondary:#f8f9fa;--border-color:#eaeaea;--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;color:var(--text-color);background-color:var(--bg-color);height:100vh;display:flex;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);color:var(--text-color);width:40px;height:40px;border-radius:50%;display:flex;align-items:center;justify-content:center;cursor:pointer;transition:all .2s ease}
+.theme-toggle:hover{background:var(--border-color)}
+.logo{margin-bottom:1.5rem;display:flex;align-items:center}
+.logo svg{height:48px;width:auto}
+.logo-text{font-family:'PT Mono',monospace;font-weight:700;font-size:2em;margin-left:.25em}
+h1{font-size:3rem;font-weight:700;margin-bottom:1rem;letter-spacing:-.02em}
+.tagline{font-size:1.25rem;color:var(--text-light);margin-bottom:2rem;font-weight:400}
+.features{display:grid;grid-template-columns:repeat(2,1fr);gap:1.5rem;margin-bottom:2rem}
+.feature{display:flex;align-items:flex-start;gap:.75rem}
+.feature-icon{background-color:var(--primary-color);color:#fff;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;margin-bottom:2rem}
+.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:all .2s ease}
+.btn-primary{background-color:var(--primary-color);color:#fff;border:none}
+.btn-primary:hover{background-color:var(--primary-hover)}
+.btn-secondary{background-color:var(--bg-secondary);color:var(--text-color);border:1px solid var(--border-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 ease}
+.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:all .3s ease;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%)}
+body[data-theme="light"] .preview-image .light-img{display:block}
+body[data-theme="light"] .preview-image .dark-img{display:none}
+body[data-theme="dark"] .preview-image .light-img{display:none}
+body[data-theme="dark"] .preview-image .dark-img{display:block}
+@media (max-width: 1400px) {
+:root{--container-padding:3rem}
+.preview-stack{transform:translateX(15%)}
 }
-  
-  * {
-    margin: 0;
-    padding: 0;
-    box-sizing: border-box;
-  }
-  
-  body {
-    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-    line-height: 1.5;
-    color: var(--text-color);
-    background-color: var(--bg-color);
-    height: 100vh;
-    display: flex;
-    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;
-
+@media (max-width: 1200px) {
+:root{--container-padding:2rem}
+.preview-side{display:none}
+.content-side{max-width:100%;padding:3rem 0}
+.header-top{right:2rem}
 }
-  
-  .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;
-
+@media (max-width: 768px) {
+:root{--container-padding:1.5rem}
+body{overflow:auto}
+.content-side{padding:2rem 0}
+h1{font-size:2.5rem}
+.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}
 }
-  
-  .theme-toggle {
-    background: var(--bg-secondary);
-    border: 1px solid var(--border-color);
-    color: var(--text-color);
-    width: 40px;
-    height: 40px;
-    border-radius: 50%;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    transition: all 0.2s ease;
-  }
-  
-  .theme-toggle:hover {
-    background: var(--border-color);
-  }
-  
-  .logo {
-    margin-bottom: 1.5rem;
-    display: flex;
-    align-items: center;
-  }
-  
-  .logo svg {
-    height: 48px;
-    width: auto;
-  }
-  
-  .logo-text {
-    font-family: 'PT Mono', monospace;
-    font-weight: 700;
-    font-size: 2em;
-    margin-left: .25em;
-
-}
-  
-  h1 {
-    font-size: 3rem;
-    font-weight: 700;
-    margin-bottom: 1rem;
-    letter-spacing: -0.02em;
-  }
-  
-  .tagline {
-    font-size: 1.25rem;
-    color: var(--text-light);
-    margin-bottom: 2rem;
-    font-weight: 400;
-  }
-  
-  .features {
-    display: grid;
-    grid-template-columns: repeat(2, 1fr);
-    gap: 1.5rem;
-    margin-bottom: 2rem;
-  }
-  
-  .feature {
-    display: flex;
-    align-items: flex-start;
-    gap: 0.75rem;
-  }
-  
-  .feature-icon {
-    background-color: var(--primary-color);
-    color: white;
-    width: 32px;
-    height: 32px;
-    border-radius: 6px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    flex-shrink: 0;
-  }
-  
-  .feature-text {
-    font-size: 0.9rem;
-  }
-  
-  .feature-text strong {
-    display: block;
-    margin-bottom: 0.25rem;
-  }
-  
-  .buttons {
-    display: flex;
-    gap: 1rem;
-    margin-bottom: 2rem;
-  }
-  
-  .btn {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.5rem;
-    padding: 0.75rem 1.5rem;
-    border-radius: 8px;
-    font-weight: 600;
-    font-size: 1rem;
-    text-decoration: none;
-    transition: all 0.2s ease;
-  }
-  
-  .btn-primary {
-    background-color: var(--primary-color);
-    color: white;
-    border: none;
-  }
-  
-  .btn-primary:hover {
-    background-color: var(--primary-hover);
-  }
-  
-  .btn-secondary {
-    background-color: var(--bg-secondary);
-    color: var(--text-color);
-    border: 1px solid var(--border-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 0.2s ease;
-  }
-  
-  .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: all 0.3s ease;
-    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%);
-
-}
-  
-  body[data-theme="light"] .preview-image .light-img {
-    display: block;
-  }
-  
-  body[data-theme="light"] .preview-image .dark-img {
-    display: none;
-  }
-  
-  body[data-theme="dark"] .preview-image .light-img {
-    display: none;
-
-}
-  
-  body[data-theme="dark"] .preview-image .dark-img {
-    display: block;
-  }
-  
-  @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;
-    }
-    
-    h1 {
-      font-size: 2.5rem;
-    }
-    
-    .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: rgb(205, 39, 39);
-
-}
+.social-links .lucide-heart-handshake{color:#cd2727}

package/config.js

@@ -18,15 +18,21 @@ module.exports = {
   srcDir: 'docs',       // Source directory for Markdown files
   outputDir: 'site',    // Directory for generated static site
 
+  // Sidebar Configuration
+  sidebar: {
+    collapsible: true,        // or false to disable
+    defaultCollapsed: false,  // or true to start collapsed
+  },
+
   // Theme Configuration
   theme: {
     name: 'sky',            // Themes: 'default', 'sky'
     defaultMode: 'light',   // Initial color mode: 'light' or 'dark'
     enableModeToggle: true, // Show UI button to toggle light/dark modes
+    positionMode: 'top', // 'top' or 'bottom' for the theme toggle
     customCss: [            // Array of paths to custom CSS files
       // '/assets/css/custom.css', // Custom TOC styles
     ],
-    // options: { /* Future: theme-specific options */ }
   },
 
   // Custom JavaScript Files
@@ -34,6 +40,9 @@ module.exports = {
      '/assets/js/docmd-image-lightbox.js', // Image lightbox functionality
   ],
 
+  // Content Processing
+  autoTitleFromH1: true, // Set to true to automatically use the first H1 as page title
+
   // Plugins Configuration (Object format)
   // Plugins are configured here. docmd will look for these keys.
   plugins: {
@@ -79,6 +88,7 @@ module.exports = {
   navigation: [
       { title: 'Welcome', path: '/', icon: 'feather' },
       { title: 'Overview', path: '/overview', icon: 'home' },
+      // { title: 'Support the Project', path: 'https://github.com/sponsors/mgks', icon: 'heart', external: true },
       {
         title: 'Getting Started',
         icon: 'rocket',
@@ -96,7 +106,19 @@ 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: 'Custom Containers', path: '/content/custom-containers', icon: 'box' },
+          {
+            title: 'Custom Containers',
+            path: '/content/containers/',
+            icon: 'box',
+            children: [
+              { title: 'Callouts', path: '/content/containers/callouts', icon: 'megaphone' },
+              { title: 'Cards', path: '/content/containers/cards', icon: 'panel-top' },
+              { title: 'Steps', path: '/content/containers/steps', icon: 'list-ordered' },
+              { title: 'Tabs', path: '/content/containers/tabs', icon: 'columns-3' },
+              { title: 'Buttons', path: '/content/containers/buttons', icon: 'mouse-pointer-click' },
+              { title: 'Nested Containers', path: '/content/containers/nested-containers', icon: 'folder-tree' },
+            ]
+          },
           { title: 'No-Style Pages', path: '/content/no-style-pages', icon: 'layout' },
           { title: 'No-Style Example', path: '/content/no-style-example', icon: 'sparkles' },
         ],
@@ -132,6 +154,13 @@ module.exports = {
       { title: 'Issues', path: 'https://github.com/mgks/docmd/issues', icon: 'badge-alert', external: true }
   ],
 
+  // Sponsor Ribbon Configuration
+  sponsor: {
+    enabled: true,                    // Enable/disable the sponsor ribbon
+    title: 'Support docmd',     // Text to display on the ribbon
+    link: 'https://github.com/sponsors/mgks', // URL for the sponsor link
+  },
+
   // Footer Configuration
   // Markdown is supported here.
   footer: '© ' + new Date().getFullYear() + ' Project docmd.',

package/docs/configuration.md

@@ -23,10 +23,16 @@ module.exports = {
   srcDir: 'docs',
   outputDir: 'site',
 
+  sidebar: {
+    collapsible: true,
+    defaultCollapsed: false,
+  },
+
   theme: {
-    name: 'sky',            // Name of the built-in theme to use (e.g., 'sky', 'default')
-    defaultMode: 'light',   // 'light' or 'dark'
-    enableModeToggle: true, // Show UI button to toggle light/dark modes
+    name: 'sky',
+    defaultMode: 'light',
+    enableModeToggle: true,
+    positionMode: 'bottom', // 'top' or 'bottom'
     customCss: [            // Array of paths to your custom CSS files
       // '/css/override-styles.css', // Paths are relative to the outputDir root
     ],
@@ -37,6 +43,14 @@ module.exports = {
     // '/js/extra-functionality.js', // Loaded at the end of the body
   ],
 
+  autoTitleFromH1: true,
+
+  sponsor: {
+    enabled: true,
+    title: 'Sponsor the Project',
+    link: 'https://github.com/sponsors/mgks',
+  },
+
   plugins: {
     // SEO Plugin Configuration
     seo: {
@@ -110,6 +124,37 @@ module.exports = {
 *   **Default:** `'site'`
 *   **Description:** Directory where the static site will be generated.
 
+### `autoTitleFromH1`
+*   **Type:** `Boolean`
+*   **Default:** `true`
+*   **Description:** If `true`, `docmd` will automatically use the content of the first H1 tag (`# Title`) as the page title if no `title` is specified in the frontmatter. If set to `false` and a page has no `title` in its frontmatter, the page header will be hidden.
+*   **Example:** 
+    ```javascript
+    // With autoTitleFromH1: true (default)
+    // Markdown file with: # My Page Title
+    // Will automatically set the page title to "My Page Title"
+    
+    // With autoTitleFromH1: false
+    // You must explicitly set title in frontmatter:
+    // ---
+    // title: "My Page Title"
+    // ---
+    ```
+
+## `sidebar` (Object)
+
+Configures the behavior of the sidebar.
+
+### `sidebar.collapsible`
+*   **Type:** `Boolean`
+*   **Default:** `false`
+*   **Description:** If `true`, a toggle button is added to the header, allowing users to show or hide the sidebar. The user's preference is saved in `localStorage`.
+
+### `sidebar.defaultCollapsed`
+*   **Type:** `Boolean`
+*   **Default:** `false`
+*   **Description:** If `sidebar.collapsible` is `true`, this option sets the default state of the sidebar to collapsed. A user's saved preference will override this.
+
 ## `theme` (Object)
 
 Configures the visual theme of your site.
@@ -131,6 +176,13 @@ Configures the visual theme of your site.
 *   **Default:** `true` (assuming it's now a core feature)
 *   **Description:** If `true`, a UI toggle button will be displayed allowing users to switch between light and dark modes. Their preference is typically saved in `localStorage`.
 
+### `theme.positionMode`
+*   **Type:** `String`
+*   **Default:** `'bottom'`
+*   **Values:** `'top'` or `'bottom'`
+*   **Description:** Sets the position of the light/dark mode toggle button. `'top'` places it in the page header (top right), while `'bottom'` places it at the bottom of the sidebar.
+*   **Example:** `positionMode: 'top'` - Useful for sites where you want the theme toggle to be more prominent and easily accessible.
+
 ### `theme.customCss`
 *   **Type:** `Array` of `String`
 *   **Default:** `[]` (empty array)
@@ -172,6 +224,23 @@ Configures the visual theme of your site.
 ## `footer` (String, Optional)
 *   **Description:** Custom footer text (Markdown supported).
 
+## `sponsor` (Object, Optional)
+*   **Type:** `Object`
+*   **Description:** Configures a sponsor ribbon that appears in the bottom-right corner of every page.
+*   **Properties:**
+    *   `enabled` (Boolean, Optional): Whether to show the sponsor ribbon. Defaults to `true` if the sponsor object is provided.
+    *   `title` (String, Optional): Text to display on the ribbon. Defaults to `'Sponsor the Project'`.
+    *   `link` (String, Required if enabled): URL for the sponsor link. Should open in a new tab.
+*   **Example:**
+    ```javascript
+    sponsor: {
+      enabled: true,
+      title: 'Sponsor the Project',
+      link: 'https://github.com/sponsors/mgks'
+    }
+    ```
+*   **Note:** The ribbon is positioned fixed in the bottom-right corner and includes a heart icon with a subtle animation.
+
 ## `favicon` (String, Optional)
 *   **Description:** Path to your favicon file, relative to `outputDir` root.