@mgks/docmd 0.1.3 → 0.2.0

package/docs/configuration.md

@@ -23,10 +23,16 @@ module.exports = {
   srcDir: 'docs',
   outputDir: 'site',
 
+  sidebar: {
+    collapsible: true,
+    defaultCollapsed: false,
+  },
+
   theme: {
-    name: 'default',        // Name of the built-in theme to use (e.g., 'default', 'classic')
-    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,20 +43,40 @@ module.exports = {
     // '/js/extra-functionality.js', // Loaded at the end of the body
   ],
 
-  plugins: [
-    // Example: Enable built-in SEO enhancements
-    // ['seo', {
-    //   defaultDescription: 'A fantastic site about interesting things.',
-    //   openGraph: { defaultImage: '/assets/images/og-social-default.png' },
-    //   twitter: { cardType: 'summary_large_image', siteUsername: '@MyProject' }
-    // }],
+  autoTitleFromH1: true,
 
-    // Example: Enable Google Analytics (Universal Analytics)
-    // ['analytics-google-ua', { trackingId: 'UA-XXXXXXXXX-Y' }],
+  sponsor: {
+    enabled: true,
+    title: 'Sponsor the Project',
+    link: 'https://github.com/sponsors/mgks',
+  },
 
-    // Example: Enable Google Analytics 4
-    // ['analytics-google-v4', { measurementId: 'G-XXXXXXXXXX' }],
-  ],
+  plugins: {
+    // SEO Plugin Configuration
+    seo: {
+      defaultDescription: 'A fantastic site about interesting things.',
+      openGraph: { 
+        defaultImage: '/assets/images/og-social-default.png'
+      },
+      twitter: { 
+        cardType: 'summary_large_image', 
+        siteUsername: '@MyProject' 
+      }
+    },
+
+    // Google Analytics 4
+    analytics: {
+      googleV4: { 
+        measurementId: 'G-XXXXXXXXXX' 
+      }
+    },
+    
+    // Sitemap generation
+    sitemap: {
+      defaultChangefreq: 'weekly',
+      defaultPriority: 0.8
+    }
+  },
 
   navigation: [
     { title: 'Home', path: '/', icon: 'home' }, // Icon names correspond to SVGs
@@ -98,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.
@@ -119,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)
@@ -137,15 +201,15 @@ Configures the visual theme of your site.
 *   **Paths:** Should be relative to the `outputDir` root (e.g., `'/js/my-analytics-alternative.js'`).
 *   **Example:** `customJs: ['/assets/js/interactive-component.js']`
 
-## `plugins` (Array)
-*   **Type:** `Array`
-*   **Default:** `[]`
-*   **Description:** An array to configure and enable plugins. `docmd` will ship with some core "local" plugins (like SEO and Analytics) that you can enable here. Future versions might support third-party plugins.
-*   **Format:** Each item in the array is typically another array: `['plugin-name', { pluginOptions }]` or a direct `require()` for local project plugins (advanced usage).
+## `plugins` (Object)
+*   **Type:** `Object`
+*   **Default:** `{}`
+*   **Description:** An object to configure and enable plugins. `docmd` ships with core plugins like SEO, Analytics, and Sitemap that you can configure here.
+*   **Format:** Each key in the object represents a plugin name, and its value is an object containing the plugin's configuration options.
 *   **Built-in Plugin Examples:**
-    *   `['seo', { defaultDescription: '...', openGraph: { ... }, ... }]`
-    *   `['analytics-google-ua', { trackingId: 'UA-...' }]`
-    *   `['analytics-google-v4', { measurementId: 'G-...' }]`
+    *   `seo: { defaultDescription: '...', openGraph: { ... }, ... }`
+    *   `analytics: { googleV4: { measurementId: 'G-XXXXXXXXXX' } }`
+    *   `sitemap: { defaultChangefreq: 'weekly', defaultPriority: 0.8 }`
 *   **See Also:** [Plugins](/plugins/)
 
 ## `navigation` (Array of Objects)
@@ -160,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.
 

package/docs/content/containers/buttons.md

@@ -0,0 +1,88 @@
+---
+title: "Container: Buttons"
+description: "How to create stylish, clickable buttons within your documentation for calls to action."
+---
+
+# Buttons
+
+The `button` container allows you to easily create a stylish, clickable button. It's perfect for calls to action, such as linking to a download page, an external resource, or another section of your documentation.
+
+## Usage
+
+The button container is a self-contained component. You provide its text, URL, and an optional color as arguments.
+
+::: callout info Important Notes
+- Container blocks (like `::: button`) should be preceded by a blank line to ensure proper parsing by the markdown processor.
+:::
+
+**Syntax:**
+```markdown
+::: 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.
+-   **`/path/to/link`**: The URL the button should link to. For internal links, use relative paths.
+-   **`external:/external-url`**: For external links that should open in a new tab, prefix the URL with `external:`.
+-   **`[color:#hexcode]`**: (Optional) A custom background color for the button. If omitted, it will use the theme's default link color.
+
+---
+
+## Examples
+
+### Standard Internal Button
+
+This button will use the default theme color and link to a section on the current page.
+
+**Code:**
+```markdown
+::: button View_Examples #examples
+```
+
+**Rendered Preview:**
+::: button View_Examples #examples
+
+### External Link Button
+
+External links open in a new tab for better user experience.
+
+**Code:**
+```markdown
+::: button GitHub_Repository external:https://github.com/mgks/docmd
+```
+
+**Rendered Preview:**
+::: button GitHub_Repository external:https://github.com/mgks/docmd
+
+### Button with Custom Color
+
+You can easily override the color for emphasis.
+
+**Code:**
+```markdown
+::: button Getting_Started #getting-started color:#28a745
+```
+
+**Rendered Preview:**
+::: button Getting_Started #getting-started color:#28a745
+
+### Buttons Inside Other Containers
+
+Buttons are flexible and can be placed inside other containers, like cards or callouts, to create powerful components. This nesting is now reliable.
+
+**Code:**
+
+```markdown
+::: 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/
+:::
+```
+
+**Rendered Preview:**
+
+::: card Feature Announcement
+Our latest feature is now available! Read the full documentation to learn more about how it works.
+
+::: button Learn_More #customization
+:::

package/docs/content/containers/callouts.md

@@ -0,0 +1,154 @@
+---
+title: "Container: Callouts"
+description: "How to use callouts to highlight important information, warnings, tips, or notes in your documentation."
+---
+
+# Callouts
+
+Callouts are perfect for drawing the user's attention to a specific piece of information. They are visually distinct from the regular text and are ideal for tips, warnings, and important notes.
+
+## Usage
+
+The basic syntax uses the `callout` container name, followed by the callout type.
+
+::: callout info
+Container blocks (like `::: callout`) should be preceded by a blank line to ensure proper parsing by the markdown processor.
+:::
+
+**Syntax:**
+```markdown
+::: callout type
+The main content of the callout.
+:::
+```
+
+**With Custom Title:**
+```markdown
+::: callout type Custom Title Here
+The main content of the callout.
+:::
+```
+
+**Parameters:**
+*   `type`: The type determines the color and styling of the callout. Available types are: `info`, `tip`, `warning`, `danger`, `success`.
+*   `Custom Title Here` (optional): Any text following the type becomes the callout title.
+
+::: callout info Auto Emojis
+Some themes (like Sky) automatically add emojis to callout titles: ℹ️ for info, ⚠️ for warning, 💡 for tip, 🚨 for danger, and ✅ for success.
+:::
+
+---
+
+## Examples
+
+### Info
+
+Use the `info` type for general notes or neutral supplementary details.
+
+**Code:**
+```markdown
+::: callout info
+This is an informational message. It's great for providing context or background information that is helpful but not critical.
+:::
+```
+
+**Rendered Preview:**
+::: callout info
+This is an informational message. It's great for providing context or background information that is helpful but not critical.
+:::
+
+**With Custom Title:**
+```markdown
+::: callout info Quick Reference
+This callout has a custom title that appears prominently at the top.
+:::
+```
+
+**Rendered Preview:**
+::: callout info Quick Reference
+This callout has a custom title that appears prominently at the top.
+:::
+
+### Tip
+
+Use the `tip` type for helpful tips, best practices, or suggestions.
+
+**Code:**
+```markdown
+::: callout tip
+Here's a helpful tip to improve your workflow. Using this shortcut can save you a lot of time!
+:::
+```
+
+**Rendered Preview:**
+::: callout tip
+Here's a helpful tip to improve your workflow. Using this shortcut can save you a lot of time!
+:::
+
+**With Custom Title:**
+```markdown
+::: callout tip Pro Tip
+Custom titles help organize your callouts and make them more scannable for readers.
+:::
+```
+
+**Rendered Preview:**
+::: callout tip Pro Tip
+Custom titles help organize your callouts and make them more scannable for readers.
+:::
+
+### Warning
+
+Use the `warning` type to indicate something that requires caution or might lead to unexpected results.
+
+**Code:**
+```markdown
+::: callout warning
+**Heads up!** Changing this setting can have unintended side effects. Please make sure you understand the consequences before proceeding.
+:::
+```
+
+**Rendered Preview:**
+::: callout warning
+**Heads up!** Changing this setting can have unintended side effects. Please make sure you understand the consequences before proceeding.
+:::
+
+### Danger
+
+Use the `danger` type for critical information, destructive actions, or security warnings.
+
+**Code:**
+```markdown
+::: callout danger
+**Critical!** This action is irreversible and will result in permanent data loss. Do not proceed unless you have a backup.
+:::
+```
+
+**Rendered Preview:**
+::: callout danger
+**Critical!** This action is irreversible and will result in permanent data loss. Do not proceed unless you have a backup.
+:::
+
+## All Callout Types with Titles
+
+Here's a quick reference showing all available callout types with custom titles:
+
+::: callout info Documentation Note
+Use info callouts for neutral supplementary information.
+:::
+
+::: callout tip Best Practice
+Use tip callouts for helpful suggestions and best practices.
+:::
+
+::: callout warning Important
+Use warning callouts for actions that require caution.
+:::
+
+::: callout danger Critical Alert
+Use danger callouts for destructive actions or critical warnings.
+:::
+
+::: callout success Task Complete
+Use success callouts to indicate completed tasks or positive outcomes.
+:::

package/docs/content/containers/cards.md

@@ -0,0 +1,93 @@
+---
+title: "Container: Cards"
+description: "How to use cards to group related content into visually distinct blocks with an optional title."
+---
+
+# Cards
+
+Cards provide a visually distinct block for grouping related content. They are a versatile component that can be used for feature overviews, summaries, or linking to other sections.
+
+## Usage
+
+The `card` container can be used with or without a title.
+
+::: callout info
+Container blocks (like `::: card`) should be preceded by a blank line to ensure proper parsing by the markdown processor.
+:::
+
+**Syntax:**
+```markdown
+::: card Optional Card Title
+The main body content of the card.
+Supports **Markdown** formatting.
+:::
+```
+-   `Optional Card Title`: If you provide text after `card`, it becomes the title of the card.
+
+---
+
+## Examples
+
+### Card with a Title
+
+This is the most common use case, where the card has a clear heading.
+
+**Code:**
+```markdown
+::: 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.
+:::
+```
+
+**Rendered Preview:**
+::: 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 without a Title
+
+If you omit the title, the content starts directly. This is ideal for small, self-contained snippets or quotes.
+
+**Code:**
+```markdown
+::: card
+This is a card without an explicit title. The content starts directly, which is great for simple, focused information.
+:::
+```
+
+**Rendered Preview:**
+::: card
+This is a card without an explicit title. The content starts directly, which is great for simple, focused information.
+:::
+
+### Nesting Content in Cards
+
+Cards are great for composition. You can easily place other elements, like buttons, inside a card to create a call to action.
+
+**Code:**
+```markdown
+::: card Download the App
+Get the latest version for your platform and start building today.
+
+::: button Learn_More #customization
+::: button View_GitHub external:https://github.com/mgks/docmd color:#5865f2
+:::
+```
+
+**Rendered Preview:**
+
+::: card Download the App
+Get the latest version for your platform and start building today.
+
+::: button Learn_More #customization
+::: button View_GitHub external:https://github.com/mgks/docmd color:#5865f2
+
+:::

package/docs/content/containers/index.md

@@ -0,0 +1,35 @@
+---
+title: "Custom Containers"
+description: "Enhance your documentation with special components like callouts, cards, steps, and tabs using docmd's custom container syntax."
+---
+
+`docmd` provides a simple syntax for adding richer, pre-styled components to your Markdown content. These are powered by the `markdown-it-container` plugin.
+
+The general syntax for simple containers like `callout` and `card` is:
+
+```markdown
+::: containerName [optionalTitleOrType]
+Content for the container goes here.
+:::
+```
+
+For more complex components like `steps` and `tabs`, we use a more robust and intuitive syntax that relies on standard Markdown, preventing common nesting issues.
+
+## Advanced Nested Container System
+
+With docmd v0.2.0, all containers support **seamless nesting** - you can nest any container within any other container to create complex, interactive documentation layouts.
+
+**New in v0.2.0:** [Learn about nested containers →](./nested-containers)
+
+## Available Containers
+
+Select a container type from the list below or from the sidebar to see detailed usage instructions and examples.
+
+- [**Callouts**](./callouts/) - For highlighting important information like notes, tips, and warnings.
+- [**Cards**](./cards/) - For grouping related content into visually distinct blocks.
+- [**Steps**](./steps/) - For presenting a sequence of instructions in a numbered format.
+- [**Tabs**](./tabs/) - For organizing content in a switchable, tabbed interface.
+- [**Buttons**](./buttons/) - For creating stylish, clickable calls to action.
+- [**Nested Containers**](./nested-containers/) - For creating complex, interactive layouts with container nesting.
+
+These custom containers allow you to create more engaging and structured documentation without needing to write custom HTML or CSS.