@mgks/docmd 0.1.4 → 0.2.0

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.

package/docs/content/containers/nested-containers.md

@@ -0,0 +1,329 @@
+---
+title: "Nested Containers"
+description: "Learn how to use the advanced nested container system to create complex, interactive documentation layouts with seamless container nesting."
+---
+
+# Nested Containers
+
+The advanced nested container system in docmd allows you to create complex, interactive documentation layouts by nesting containers within each other. This powerful feature enables you to build rich, structured content that was previously impossible.
+
+## Overview
+
+With docmd v0.2.0, you can nest containers seamlessly:
+
+- **Cards within Tabs** - Organize content into structured sections within tabs
+- **Callouts within Cards** - Add informational content within structured cards
+- **Buttons within Any Container** - Place action buttons in any context
+- **Multiple Levels of Nesting** - Support for complex nested structures up to 7+ levels
+- **Steps for Simple Sequences** - Use steps containers for straightforward, sequential instructions
+
+## Container Nesting Rules
+
+### Supported Nesting Combinations
+
+| Container | Can Nest Inside | Can Contain |
+|-----------|----------------|-------------|
+| **Callouts** | Any container | Any container |
+| **Cards** | Any container | Any container |
+| **Buttons** | Any container | None (self-closing) |
+| **Steps** | Any container (except tabs) | Any container (except tabs) |
+| **Tabs** | Any container (except steps) | Any container (except tabs, steps) |
+
+### Nesting Best Practices
+
+1. **Logical Structure** - Nest containers in a way that makes logical sense
+2. **Readability** - Don't nest too deeply (3-4 levels maximum for readability)
+3. **Performance** - Complex nesting is supported but keep it reasonable
+4. **Content Organization** - Use nesting to organize related content
+5. **Use the Right Tool** - Use steps for simple sequences, cards/tabs for complex content
+
+### Nesting Limitations
+
+::: callout error Known Issues
+**Steps ↔ Tabs Incompatibility:** Steps and tabs containers cannot be nested within each other due to parsing complexity. Use them as separate sections instead.
+:::
+
+- **Tabs cannot contain tabs** - This prevents infinite recursion
+- **Tabs cannot contain steps** - Due to parsing conflicts with markdown processing
+- **Steps cannot contain tabs** - Due to parsing complexity 
+- **Steps cannot be inside tabs** - Due to container recognition issues
+- **Maximum depth** - While technically unlimited, keep it under 7 levels for readability
+- **Performance** - Very deep nesting may impact rendering performance
+
+## Basic Nesting Examples
+
+### Cards with Nested Content
+
+```bash
+::: card Installation Guide
+
+Here's how to install the application:
+
+::: callout tip Pro Tip
+Make sure to download the correct version for your platform.
+:::
+
+::: button Download_Now /downloads
+
+:::
+```
+
+::: card Installation Guide
+
+Here's how to install the application:
+
+::: callout tip Pro Tip
+Make sure to download the correct version for your platform.
+:::
+
+::: button Download_Now /downloads
+
+:::
+
+### Tabs with Nested Content
+
+```bash
+::: tabs
+
+== tab "Windows"
+Download the Windows installer (.exe) file.
+
+::: callout tip
+Make sure to run as administrator for best results.
+:::
+
+::: button Download_Windows /downloads/windows
+
+== tab "macOS"
+Download the macOS package (.pkg) file.
+
+::: callout warning
+You may need to allow the app in Security & Privacy settings.
+:::
+
+::: button Download_macOS /downloads/macos
+
+== tab "Linux"
+Download the Linux tarball (.tar.gz) file.
+
+::: button Download_Linux /downloads/linux
+
+:::
+```
+
+::: tabs
+
+== tab "Windows"
+Download the Windows installer (.exe) file.
+
+::: callout tip
+Make sure to run as administrator for best results.
+:::
+
+::: button Download_Windows /downloads/windows
+
+== tab "macOS"
+Download the macOS package (.pkg) file.
+
+::: callout warning
+You may need to allow the app in Security & Privacy settings.
+:::
+
+::: button Download_macOS /downloads/macos
+
+== tab "Linux"
+Download the Linux tarball (.tar.gz) file.
+
+::: button Download_Linux /downloads/linux
+
+:::
+
+## Advanced Nesting Patterns
+
+### Complex Nested Structure
+
+````bash
+::: card Installation Guide
+
+**Download**
+Get the latest version for your platform.
+
+::: button Download_Now /downloads
+
+**Install**
+Run the installer and follow the prompts.
+
+```bash
+install docmd
+```
+
+**Configure**
+Set up your preferences.
+
+::: callout warning Important
+Don't forget to configure your settings!
+:::
+
+:::
+````
+
+::: card Installation Guide
+
+**Download**
+Get the latest version for your platform.
+
+::: button Download_Now /downloads
+
+**Install**
+Run the installer and follow the prompts.
+
+```bash
+install docmd
+```
+
+**Configure**
+Set up your preferences.
+
+::: callout warning Important
+Don't forget to configure your settings!
+:::
+
+:::
+
+### Cards with Multiple Nested Elements
+
+```markdown
+::: card API Reference
+
+::: callout info API Key Required
+All API requests require a valid API key.
+:::
+
+**Setup Steps**
+
+1. Get your API key from the dashboard
+2. Include it in your request headers
+3. Test your connection
+
+::: button Test_API /api/test
+
+:::
+```
+
+::: card API Reference
+
+::: callout info API Key Required
+All API requests require a valid API key.
+:::
+
+**Setup Steps**
+
+1. Get your API key from the dashboard
+2. Include it in your request headers
+3. Test your connection
+
+::: button Test_API /api/test
+
+:::
+
+## Steps Container
+
+Steps containers are designed for simple, sequential instructions and work well with other containers:
+
+```bash
+::: steps
+
+1. **Download the Application**
+   Get the latest version from our download page.
+
+   ::: button Download_Now /downloads
+
+2. **Install the Application**
+   Run the installer and follow the setup wizard.
+
+   ::: callout tip Pro Tip
+   Check our system requirements page for detailed information.
+   :::
+
+3. **Configure Settings**
+   Set up your preferences and start using the app.
+
+   ::: card Configuration
+   - Choose your theme
+   - Set up notifications
+   - Configure integrations
+   :::
+
+:::
+```
+
+::: steps
+
+1. **Download the Application**
+   Get the latest version from our download page.
+
+   ::: button Download_Now /downloads
+
+2. **Install the Application**
+   Run the installer and follow the setup wizard.
+
+   ::: callout tip Pro Tip
+   Check our system requirements page for detailed information.
+   :::
+
+3. **Configure Settings**
+   Set up your preferences and start using the app.
+
+   ::: card Configuration
+   - Choose your theme
+   - Set up notifications
+   - Configure integrations
+   :::
+
+:::
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Container not rendering** - Ensure proper spacing and syntax
+2. **Nested content not showing** - Check for proper closing tags
+3. **Performance issues** - Reduce nesting depth if experiencing slowdowns
+
+### Debugging Tips
+
+- **Check syntax** - Ensure all containers have proper opening and closing tags
+- **Verify nesting** - Make sure containers are properly nested
+- **Test incrementally** - Build complex structures step by step
+- **Use browser dev tools** - Inspect the generated HTML for issues
+- **Use the right container** - Steps for simple sequences, cards/tabs for complex content
+
+## Migration from v0.1.x
+
+### Breaking Changes
+
+- **Container parsing** - The internal parsing system has been optimized for reliability
+- **Nesting behavior** - Most containers support seamless nesting
+
+### What's New
+
+- **Enhanced nesting** - Cards, tabs, callouts, and buttons support seamless nesting
+- **Better performance** - Improved parsing performance for complex structures
+- **Clear limitations** - Well-defined boundaries for what each container can do
+
+### Backward Compatibility
+
+- **Existing syntax** - All existing container syntax remains the same
+- **Enhanced functionality** - New nesting capabilities are additive for supported containers
+
+## Future Container Types
+
+The nested container system is designed to be easily extensible. Future container types that could be added include:
+
+- **Timeline containers** - For chronological content
+- **Changelog containers** - For version history
+- **FAQ containers** - For question-answer content
+- **Gallery containers** - For image collections
+- **Code playground containers** - For interactive code examples
+
+The architecture supports adding new containers by simply defining them in the containers object and implementing their render functions.