@mgks/docmd 0.1.4 → 0.2.0

package/docs/content/containers/steps.md

@@ -0,0 +1,175 @@
+---
+title: "Steps Container"
+description: "Create step-by-step instructions and tutorials with the steps container."
+---
+
+# Steps Container
+
+The steps container allows you to create clear, sequential instructions and tutorials. It automatically numbers your steps and provides a clean, organized layout.
+
+## Basic Usage
+
+**Code:**
+
+```markdown
+::: steps
+
+1. **Create a new project**
+   Initialize your project with the necessary configuration files.
+
+2. **Install dependencies**
+   Run the package manager to install required libraries.
+
+3. **Start development**
+   Begin coding your application with the setup complete.
+
+   ::: button Learn_More #customization color:green
+
+:::
+```
+
+**Rendered Preview:**
+
+::: steps
+
+1. **Create a new project**
+   Initialize your project with the necessary configuration files.
+
+2. **Install dependencies**
+   Run the package manager to install required libraries.
+
+3. **Start development**
+   Begin coding your application with the setup complete.
+
+   ::: button Learn_More #customization color:green
+
+:::
+
+## Steps with Nested Containers
+
+You can include cards, callouts, and buttons inside steps for richer content:
+
+**Code:**
+
+```markdown
+::: steps
+
+1. **Plan Your Project**
+   Define the scope and requirements for your application.
+
+   ::: callout info Planning Tip
+   Consider creating user stories to better understand your requirements.
+   :::
+
+2. **Setup Development Environment**
+   Configure your local development tools and workspace.
+
+   ::: card Environment Checklist
+   - Install code editor (VS Code recommended)
+   - Setup version control (Git)
+   - Install Node.js and npm
+   - Configure linting and formatting tools
+   :::
+
+3. **Initialize Project**
+   Create the project structure and configuration files.
+
+   ::: button Create_Project external:https://github.com/new color:blue
+
+4. **Start Coding**
+   Begin implementing your application features.
+
+   ::: callout success Ready to Code
+   Your development environment is now ready! Happy coding!
+   :::
+
+:::
+```
+
+**Rendered Preview:**
+
+::: steps
+
+1. **Plan Your Project**
+   Define the scope and requirements for your application.
+
+   ::: callout info Planning Tip
+   Consider creating user stories to better understand your requirements.
+   :::
+
+2. **Setup Development Environment**
+   Configure your local development tools and workspace.
+
+   ::: card Environment Checklist
+   - Install code editor (VS Code recommended)
+   - Setup version control (Git)
+   - Install Node.js and npm
+   - Configure linting and formatting tools
+   :::
+
+3. **Initialize Project**
+   Create the project structure and configuration files.
+
+   ::: button Create_Project external:https://github.com/new color:blue
+
+4. **Start Coding**
+   Begin implementing your application features.
+
+   ::: callout success Ready to Code
+   Your development environment is now ready! Happy coding!
+   :::
+
+:::
+
+## Steps and Tabs Compatibility
+
+::: callout error Important Limitation
+**Steps and tabs containers are incompatible** - they cannot be nested within each other due to markdown parsing conflicts. Use them as separate sections instead.
+
+**Supported in steps:** Cards, callouts, buttons  
+**Not supported:** Tabs containers
+:::
+
+**Code:**
+
+```markdown
+## Installation Steps
+
+::: steps
+
+1. **Choose Your Platform**
+   Select the appropriate installation method for your operating system.
+
+2. **Download the Installer**
+   Get the latest version from the downloads section.
+
+3. **Run Installation**
+   Follow the setup wizard to complete installation.
+
+:::
+
+## Platform-Specific Instructions
+
+::: tabs
+== tab "Windows"
+Download the `.exe` installer and run as administrator.
+
+::: button Learn_More #customization
+
+== tab "macOS" 
+Download the `.dmg` file and drag to Applications folder.
+
+::: button Learn_More #customization
+
+:::
+```
+
+## Customization
+
+Steps containers automatically apply consistent styling and numbering. The container handles:
+
+- **Automatic numbering** - Steps are numbered sequentially
+- **Consistent spacing** - Proper spacing between steps
+- **Responsive design** - Works on all screen sizes
+- **Theme integration** - Matches your site's theme
+- **Smart list handling** - Only step items get special styling, nested lists remain normal

package/docs/content/containers/tabs.md

@@ -0,0 +1,228 @@
+---
+title: "Tabs Container"
+description: "Create tabbed content sections with the tabs container for organizing related information."
+---
+
+# Tabs Container
+
+The tabs container allows you to organize content into multiple tabbed sections, making it easy to present related information in a clean, organized way.
+
+## Basic Usage
+
+```markdown
+::: tabs
+
+== tab "First Tab"
+Content for the first tab goes here.
+
+== tab "Second Tab"
+Content for the second tab goes here.
+
+== tab "Third Tab"
+Content for the third tab goes here.
+
+:::
+```
+
+::: tabs
+
+== tab "First Tab"
+Content for the first tab goes here.
+
+== tab "Second Tab"
+Content for the second tab goes here.
+
+== tab "Third Tab"
+Content for the third tab goes here.
+
+:::
+
+## Tabs with Nested Content
+
+### Tabs with Buttons
+
+```markdown
+::: tabs
+
+== tab "Download"
+Get the latest version of our application.
+
+::: button Download_Here external:https://github.com/mgks/docmd/releases
+::: button Learn_More #advanced-tabs
+::: button NPM_Package external:https://www.npmjs.com/package/@mgks/docmd
+
+== tab "Documentation"
+Read our comprehensive documentation.
+
+::: button View_Getting_Started #basic-usage
+::: button API_Reference external:https://github.com/mgks/docmd/wiki
+::: button View_Examples #advanced-tabs
+
+:::
+```
+
+::: tabs
+
+== tab "Download"
+Get the latest version of our application.
+
+::: button Download_Here external:https://github.com/mgks/docmd/releases
+::: button Learn_More #advanced-tabs
+::: button NPM_Package external:https://www.npmjs.com/package/@mgks/docmd
+
+== tab "Documentation"
+Read our comprehensive documentation.
+
+::: button View_Getting_Started #basic-usage
+::: button API_Reference external:https://github.com/mgks/docmd/wiki
+::: button View_Examples #advanced-tabs
+
+:::
+
+### Tabs with Callouts
+
+```markdown
+::: tabs
+
+== tab "Getting Started"
+Welcome to our platform!
+
+::: callout info Welcome
+This is your first time here. Let's get you started!
+:::
+
+::: callout tip Pro Tip
+Check out our quick start guide for the fastest setup.
+:::
+
+== tab "Advanced Features"
+Explore advanced functionality.
+
+::: callout warning Important
+Some features require additional configuration.
+:::
+
+::: callout success Ready
+You're all set to explore advanced features!
+:::
+
+:::
+```
+
+::: tabs
+
+== tab "Getting Started"
+Welcome to our platform!
+
+::: callout info Welcome
+This is your first time here. Let's get you started!
+:::
+
+::: callout tip Pro Tip
+Check out our quick start guide for the fastest setup.
+:::
+
+== tab "Advanced Features"
+Explore advanced functionality.
+
+::: callout warning Important
+Some features require additional configuration.
+:::
+
+::: callout success Ready
+You're all set to explore advanced features!
+:::
+
+:::
+
+## Complex Nested Structure
+
+````bash
+::: tabs
+
+== tab "Nested Card Example"
+::: card Installation Guide
+
+**Download**
+Get the latest version for your platform.
+
+::: button Get_Latest external:https://github.com/mgks/docmd/releases
+
+**Install**
+Run the installer and follow the prompts.
+
+```bash
+install docmd
+```
+
+:::
+
+== tab "Callout Example"
+
+**Configure**
+Set up your preferences.
+
+::: callout warning Configuration
+Don't forget to configure your settings!
+:::
+
+:::
+````
+
+::: tabs
+
+== tab "Nested Card Example"
+::: card Installation Guide
+
+**Download**
+Get the latest version for your platform.
+
+::: button Get_Latest external:https://github.com/mgks/docmd/releases
+
+**Install**
+Run the installer and follow the prompts.
+
+```bash
+install docmd
+```
+
+:::
+
+== tab "Callout Example"
+
+**Configure**
+Set up your preferences.
+
+::: callout warning Configuration
+Don't forget to configure your settings!
+:::
+
+:::
+
+## Customization
+
+Tabs containers automatically handle:
+
+- **Responsive design** - Works on all screen sizes
+- **Theme integration** - Matches your site's theme
+- **Accessibility** - Proper ARIA labels and keyboard navigation
+- **Smooth transitions** - Elegant tab switching animations
+
+## Best Practices
+
+1. **Clear Labels** - Use descriptive tab names
+2. **Consistent Content** - Keep similar content types in each tab
+3. **Logical Order** - Arrange tabs in a logical sequence
+4. **Not Too Many** - Limit to 5-7 tabs for best usability
+5. **Mobile Friendly** - Consider mobile users when organizing content
+
+## Nesting Limitations
+
+::: callout error Important Limitation
+**Steps containers cannot be used inside tabs** due to parsing conflicts. If you need step-by-step instructions within tabs, use regular numbered lists or consider restructuring your content.
+:::
+
+- **Tabs cannot contain tabs** - This prevents infinite recursion
+- **Steps inside tabs not supported** - Use regular ordered lists instead
+- **Maximum depth** - While technically unlimited, keep it under 7 levels for readability
+- **Performance** - Very deep nesting may impact rendering performance

package/docs/content/frontmatter.md

@@ -50,6 +50,7 @@ Examples of custom fields you *might* add (these are not built-in features):
 *   `order`: 2 (For custom sorting of pages within a section, if you implement logic for it)
 *   `draft`: true (To mark a page as a draft, if you implement logic to exclude drafts from builds)
 *   `tags`: ["tag1", "tag2"]
+*   `permalink`: "https://example.com/your-canonical-url/" (Sets the canonical URL for SEO purposes)
 
 ## Example Usage
 
@@ -72,5 +73,4 @@ In this example:
 *   The `<meta name="description">` will be set.
 *   The `order: 1` field is available if you later want to sort "guides" pages by this value.
 
-Using frontmatter consistently ensures your pages are well-defined, SEO-friendly, and integrate smoothly with `docmd`'s navigation and theming systems.
-```
+Using frontmatter consistently ensures your pages are well-defined, SEO-friendly, and integrate smoothly with `docmd`'s navigation and theming systems.

package/docs/index.md

@@ -10,9 +10,6 @@ components:
   scripts: false
 customHead: |
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="preconnect" href="https://fonts.googleapis.com">
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=PT+Mono:wght@700&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="/assets/css/welcome.css">
   <script>
     // Initialize theme from localStorage or system preference
@@ -124,16 +121,16 @@ customHead: |
   <div class="preview-side">
     <div class="preview-stack">
       <div class="preview-image top">
-        <img src="/assets/images/preview-light-1.png" alt="docmd documentation preview" class="light-img">
-        <img src="/assets/images/preview-dark-1.png" alt="docmd documentation preview" class="dark-img">
+        <img src="/assets/images/preview-light-1.webp" alt="docmd documentation preview" class="light-img" loading="lazy">
+        <img src="/assets/images/preview-dark-1.webp" alt="docmd documentation preview" class="dark-img" loading="lazy">
       </div>
       <div class="preview-image middle">
-        <img src="/assets/images/preview-light-2.png" alt="docmd documentation preview" class="light-img">
-        <img src="/assets/images/preview-dark-2.png" alt="docmd documentation preview" class="dark-img">
+        <img src="/assets/images/preview-light-2.webp" alt="docmd documentation preview" class="light-img" loading="lazy">
+        <img src="/assets/images/preview-dark-2.webp" alt="docmd documentation preview" class="dark-img" loading="lazy">
       </div>
       <div class="preview-image bottom">
-        <img src="/assets/images/preview-light-3.png" alt="docmd documentation preview" class="light-img">
-        <img src="/assets/images/preview-dark-3.png" alt="docmd documentation preview" class="dark-img">
+        <img src="/assets/images/preview-light-3.webp" alt="docmd documentation preview" class="light-img" loading="lazy">
+        <img src="/assets/images/preview-dark-3.webp" alt="docmd documentation preview" class="dark-img" loading="lazy">
       </div>
     </div>
   </div>

package/docs/plugins/seo.md

@@ -62,6 +62,7 @@ image: "/assets/images/widgets/super-widget-social.jpg" # Used for og:image and
 ogType: "article" # Specify Open Graph type, e.g., article, website
 twitterCreator: "@widgetMaster"
 keywords: "widget, configuration, advanced, performance, security" # Optional, some argue keywords meta tag is less relevant now
+permalink: "https://example.com/docs/widgets/advanced-configuration" # Canonical URL
 ---
 
 # Advanced Widget Configuration
@@ -75,5 +76,6 @@ Supported frontmatter fields that the `seo` plugin may look for:
 *   `twitterCard` (Overrides `config.seo.twitter.cardType` for this page)
 *   `twitterCreator` (Overrides `config.seo.twitter.creatorUsername` for this page)
 *   `noindex` (Boolean): If `true`, adds `<meta name="robots" content="noindex">` to discourage search engines from indexing this specific page.
+*   `permalink` (String): If provided, sets a canonical URL for the page. This is useful when you have duplicate content across different URLs and want to indicate the preferred version. If not specified, the page's URL will be used as the canonical URL. (Note: `canonicalUrl` is also supported for backward compatibility)
 
 By configuring the `seo` plugin and utilizing frontmatter effectively, you can significantly improve how your documentation is presented and discovered online.

package/docs/theming/available-themes.md

@@ -12,8 +12,8 @@ description: "An overview of the built-in themes provided by docmd."
 module.exports = {
   // ...
   theme: {
-    name: 'theme-name', // Options: 'default', 'sky', 'ruby'
-    defaultMode: 'light', // or 'dark'
+    name: 'theme-name', // Options: 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'light', // or 'dark' to set as landing mode
     // ...
   },
   // ...
@@ -52,6 +52,20 @@ module.exports = {
     *   Luxurious dark mode with deep, rich backgrounds and vibrant accent colors
 *   **When to use:** When you want your documentation to have a distinctive, premium feel with rich colors and elegant typography.
 
+## 4. `retro` Theme
+
+*   **`theme.name: 'retro'`**
+*   **Description:** A nostalgic theme inspired by 1980s-90s computing aesthetics. It features:
+    *   Terminal-style black backgrounds with phosphor green text in dark mode
+    *   Light mode with dark green text on light gray backgrounds
+    *   Monospace typography (Fira Code) for authentic retro feel
+    *   Neon accent colors (cyan, pink, amber) with glow effects
+    *   Animated scanlines and CRT flicker effects
+    *   Terminal-style code blocks with `[TERMINAL]` labels
+    *   Retro-styled containers with pixel-art inspired elements
+    *   Blinking cursor effects on links and active elements
+*   **When to use:** Perfect for developer tools, gaming documentation, tech blogs with vintage computing focus, or anyone wanting a unique, eye-catching retro aesthetic.
+
 ## How Themes Work
 
 Each theme consists of CSS files located within `docmd`'s internal assets. When you select a theme name, `docmd` links the corresponding stylesheet in your site's HTML:
@@ -59,5 +73,6 @@ Each theme consists of CSS files located within `docmd`'s internal assets. When
 - `default` theme uses the base CSS with no additional theme stylesheet
 - `sky` theme loads `docmd-theme-sky.css` with its custom styling on top of the default CSS
 - `ruby` theme loads `docmd-theme-ruby.css` with its custom styling on top of the default CSS
+- `retro` theme loads `docmd-theme-retro.css` with its custom styling on top of the default CSS
 
 You can further customize any chosen theme using the `theme.customCss` option in your `config.js` to add your own overrides or additional styles. See [Custom CSS & JS](/theming/custom-css-js/) for details.

package/docs/theming/light-dark-mode.md

@@ -16,9 +16,10 @@ You can set the default theme for your site in the `config.js` file:
 module.exports = {
   // ... other config ...
   theme: {
-    name: 'default', // or 'sky'
+    name: 'default', // or 'sky', 'ruby', 'retro'
     defaultMode: 'dark', // Can be 'light' or 'dark'
     enableModeToggle: true, // Enable the toggle button in the UI
+    positionMode: 'bottom', // 'top' or 'bottom' - where to show the toggle
   },
   // ...
 };
@@ -26,7 +27,9 @@ module.exports = {
 
 * `defaultMode: 'light'`: The site will initially render with the light color scheme.
 * `defaultMode: 'dark'`: The site will initially render with the dark color scheme.
-* `enableModeToggle: true`: Shows a toggle button in the sidebar for users to switch modes.
+* `enableModeToggle: true`: Shows a toggle button for users to switch modes.
+* `positionMode: 'bottom'`: Places the toggle button at the bottom of the sidebar (default).
+* `positionMode: 'top'`: Places the toggle button in the page header (top right).
 
 If `defaultMode` is not specified, it defaults to `'light'`.
 
@@ -62,16 +65,22 @@ body {
 
 ## User Preference Toggle
 
-When `enableModeToggle` is set to `true`, a toggle button appears in the sidebar that allows users to switch between light and dark modes:
+When `enableModeToggle` is set to `true`, a toggle button appears that allows users to switch between light and dark modes. The position of this button is controlled by the `positionMode` setting:
 
 ```javascript
 // config.js
 theme: {
   defaultMode: 'light',
   enableModeToggle: true, // Shows the toggle button
+  positionMode: 'bottom', // 'bottom' (sidebar) or 'top' (header)
 },
 ```
 
+### Toggle Button Positions
+
+- **`positionMode: 'bottom'`** (default): The toggle button appears at the bottom of the sidebar
+- **`positionMode: 'top'`**: The toggle button appears in the page header (top right corner)
+
 The toggle button uses Lucide icons (`sun` and `moon`) to indicate the current mode and what will happen when clicked.
 
 ### User Preference Persistence

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "bin": {
-    "docmd": "./bin/docmd.js"
+    "docmd": "bin/docmd.js"
   },
   "scripts": {
     "start": "node ./bin/docmd.js dev",
@@ -43,9 +43,12 @@
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
     "lucide-static": "^0.508.0",
-    "markdown-it": "^14.1.0",
+    "markdown-it-abbr": "^2.0.0",
     "markdown-it-attrs": "^4.3.1",
     "markdown-it-container": "^4.0.0",
+    "markdown-it-deflist": "^3.0.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-task-lists": "^2.1.1",
     "ws": "^8.17.0"
   },
   "devDependencies": {
@@ -53,5 +56,8 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-node": "^11.1.0",
     "prettier": "^3.2.5"
+  },
+  "directories": {
+    "doc": "docs"
   }
 }