@mgks/docmd 0.1.4 → 0.2.1

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/custom-containers.md

@@ -1,129 +1,24 @@
 ---
 title: "Custom Containers"
 description: "Enhance your documentation with special components like callouts, cards, and steps using docmd's custom container syntax."
+noStyle: true
+components:
+  meta: false
+  favicon: true
+  css: false
+  theme: false
+  scripts: false
+customHead: |
+  <script>
+    window.location.href = "https://docmd.mgks.dev/content/containers/";
+    document.addEventListener("DOMContentLoaded", function () {
+        window.location.href = "https://docmd.mgks.dev/content/containers/";
+    });
+  </script>
+bodyClass: "no-style-example"
 ---
 
-# Custom Containers
-
-`docmd` provides a simple syntax for adding richer, pre-styled components to your Markdown content using "custom containers." These are powered by the `markdown-it-container` plugin.
-
-The general syntax is:
-
-```
-::: containerName [optionalTitleOrType]
-Content for the container goes here.
-It can span **multiple lines** and include other *Markdown* elements.
-:::
-```
-
-## Callouts
-
-Callouts are useful for highlighting important information, warnings, tips, or notes.
-
-**Syntax:**
-```
-::: callout type
-Content of the callout.
-:::
-```
-*   `type`: Can be `info`, `warning`, `tip`, or `danger`.
-
-**Examples:**
-
-::: callout info
-This is an informational message. It's good for general notes or neutral supplementary details.
-:::
-
-::: callout warning
-**Watch out!** This indicates something that requires caution or might lead to unexpected results if ignored.
-:::
-
-::: callout tip
-Here's a helpful tip or a best practice suggestion to improve a process or understanding.
-:::
-
-::: callout danger
-**Critical!** This highlights a potential risk, a destructive action, or something that must be avoided.
-:::
-
-## Cards
-
-Cards provide a visually distinct block for grouping related content, often with a title.
-
-**Syntax:**
-```
-::: card Optional Card Title
-The main body content of the card.
-Supports **Markdown** formatting.
-- List item 1
-- List item 2
-:::
-```
-*   `Optional Card Title`: If provided after `card`, it becomes the title of the card.
-
-**Example:**
-
-::: card My Feature Overview
-This card describes an amazing feature.
-* It's easy to use.
-* It solves a common problem.
-
-Learn more by reading the full guide.
-:::
-
-::: card
-This is a card without an explicit title. The content starts directly.
-Ideal for small, self-contained snippets.
-:::
-
-## Steps
-
-The "steps" container is designed for presenting a sequence of actions or instructions, often in a numbered or ordered fashion.
-
-**Syntax:**
-
-```
-::: steps
-> 1. **First Step Title:**
-> Description of the first step.
-
-> 2. **Second Step Title:**
-> Description of the second step.
-
-> *. **Using Asterisk:**
-> Alternative numbering style.
-
-> **No Number:**
-> Without a number.
-:::
-```
-
-**How it works:**
-
-The steps container uses blockquotes (`>`) to define individual steps. Start each step with a number or asterisk followed by a period, then the step title in bold. The content after the title becomes the step content.
-
-**Example:**
-
-::: steps
-> 1. **Install Dependencies:**
-> First, make sure you have Node.js and npm installed. Then, run:
->
-> ```bash
-> npm install my-package
-> ```
-
-> 2. **Configure the Settings:**
-> Open the `config.json` file and update the `apiKey` with your credentials.
-
-> 3. **Run the Application:**
-> Start the application using:
->
-> ```bash
-> npm start
-> ```
->
-> You should see "Application started successfully!" in your console.
-:::
-:::
-
-These custom containers allow you to create more engaging and structured documentation without needing to write custom HTML or CSS for common patterns. Experiment with them to see how they can improve your content's clarity and visual appeal.
+<div class="container">
+    Redirecting...<br/>
+    /custom-containers have moved to /containers now <a href="https://docmd.mgks.dev/content/containers/">Visit New Custom Containers Page</a>
+</div> 

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/content/no-style-example.md

@@ -8,6 +8,8 @@ components:
   css: true
   theme: true
   scripts: true
+  mainScripts: true
+copyCode: true
 customHead: |
   <style>
     body {

package/docs/content/no-style-pages.md

@@ -17,7 +17,9 @@ docmd offers a "no-style" page format that gives you maximum flexibility to crea
 
 To create a no-style page, add `noStyle: true` to your page's frontmatter. This tells docmd to use a special template that only includes the components you explicitly request.
 
-By default, a no-style page will render just your content with minimal HTML structure. You can then selectively enable specific components via the `components` object in frontmatter.
+By default, a no-style page will render just your content with minimal HTML structure. **All components are disabled by default** and must be explicitly enabled via the `components` object in frontmatter.
+
+> **Note:** This behavior changed in v0.2.0. Previously, some components were enabled by default and had to be disabled. Now all components are opt-in only.
 
 ## HTML Support
 
@@ -36,7 +38,7 @@ description: "Welcome to my project"
 noStyle: true
 components:
   meta: true  # Include meta tags, title, description
-  css: false  # Don't include default CSS
+  # css: false  # Not needed - CSS is disabled by default
 ---
 
 <div style="text-align: center; padding: 50px;">
@@ -48,32 +50,35 @@ components:
 
 ## Available Components
 
-You can control exactly which components are included in your page by setting them to `true` or `false` in the `components` object:
-
-| Component | Description | Default |
-|-----------|-------------|---------|
-| `meta` | Meta tags, title, description | `true` |
-| `siteTitle` | Include site title after page title | `true` |
-| `favicon` | Include favicon | `true` |
-| `css` | Include main CSS | `false` |
-| `highlight` | Include syntax highlighting CSS | `false` |
-| `theme` | Include theme-specific CSS | `false` |
-| `customCss` | Include custom CSS files from config | `false` |
-| `pluginStyles` | Include plugin-specific CSS | `false` |
-| `pluginHeadScripts` | Include plugin scripts in head | `false` |
-| `layout` | Use main content layout (`true`, `'full'`, or `false`) | `false` |
-| `sidebar` | Include sidebar | `false` |
-| `header` | Include page header | `false` |
-| `pageTitle` | Include page title in header | `false` |
-| `footer` | Include page footer | `false` |
-| `branding` | Include docmd branding in footer | `false` |
-| `logo` | Include logo in sidebar | `false` |
-| `navigation` | Include navigation in sidebar | `false` |
-| `themeToggle` | Include theme toggle button | `false` |
-| `toc` | Include table of contents | `false` |
-| `scripts` | Include all scripts | `false` |
-| `customJs` | Include custom JS files from config | `false` |
-| `pluginBodyScripts` | Include plugin scripts at end of body | `false` |
+You can control exactly which components are included in your page by setting them to `true` in the `components` object. **All components are disabled by default** and must be explicitly enabled:
+
+| Component | Description | Required Setting |
+|-----------|-------------|------------------|
+| `meta` | Meta tags, title, description | `meta: true` |
+| `siteTitle` | Include site title after page title | `siteTitle: true` |
+| `favicon` | Include favicon | `favicon: true` |
+| `css` | Include main CSS | `css: true` |
+| `highlight` | Include syntax highlighting CSS | `highlight: true` |
+| `theme` | Include theme-specific CSS | `theme: true` |
+| `themeMode` | Include theme mode toggle functionality | `themeMode: true` |
+| `customCss` | Include custom CSS files from config | `customCss: true` |
+| `pluginStyles` | Include plugin-specific CSS | `pluginStyles: true` |
+| `pluginHeadScripts` | Include plugin scripts in head | `pluginHeadScripts: true` |
+| `layout` | Use main content layout (`true`, `'full'`, or `false`) | `layout: true` or `layout: 'full'` |
+| `sidebar` | Include sidebar | `sidebar: true` |
+| `header` | Include page header | `header: true` |
+| `pageTitle` | Include page title in header | `pageTitle: true` |
+| `footer` | Include page footer | `footer: true` |
+| `branding` | Include docmd branding in footer | `branding: true` |
+| `logo` | Include logo in sidebar | `logo: true` |
+| `navigation` | Include navigation in sidebar | `navigation: true` |
+| `themeToggle` | Include theme toggle button | `themeToggle: true` |
+| `toc` | Include table of contents | `toc: true` |
+| `scripts` | Enable script loading (required for other script components) | `scripts: true` |
+| `mainScripts` | Include main JavaScript (copy code, theme toggle, etc.) | `mainScripts: true` |
+| `lightbox` | Include image lightbox functionality | `lightbox: true` |
+| `customJs` | Include custom JS files from config | `customJs: true` |
+| `pluginBodyScripts` | Include plugin scripts at end of body | `pluginBodyScripts: true` |
 
 ## Layout Options
 
@@ -83,6 +88,22 @@ The `components.layout` property has three possible values:
 - `true`: Use the main content layout with optional header and footer
 - `'full'`: Same as `true`, a full layout with content area
 
+## Script Components
+
+Script components work in a hierarchical manner:
+
+1. **`scripts: true`** - Enables script loading (required for all other script components)
+2. **`mainScripts: true`** - Includes main JavaScript functionality (copy code, theme toggle, etc.)
+3. **`lightbox: true`** - Includes image lightbox functionality (requires `mainScripts: true`)
+
+**Example:**
+```yaml
+components:
+  scripts: true      # Enable script loading
+  mainScripts: true  # Include main JavaScript
+  lightbox: true     # Include lightbox (requires mainScripts)
+```
+
 ## Sidebar Option
 
 If you set `components.sidebar: true`, the sidebar will be included with optional logo, navigation, and theme toggle button.
@@ -124,12 +145,15 @@ components:
   favicon: true
   css: true
   theme: true
+  themeMode: true
   layout: true
   header: true
   pageTitle: true
   footer: true
   branding: true
   scripts: true
+  mainScripts: true
+  lightbox: true
 customHead: |
   <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;600&display=swap" rel="stylesheet">
   <style>