@mgks/docmd 0.3.1 → 0.3.3

package/docs/content/custom-containers.md

@@ -1,24 +0,0 @@
----
-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"
----
-
-<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

@@ -1,84 +0,0 @@
----
-title: "Frontmatter"
-description: "How to use YAML frontmatter to define page metadata in your docmd Markdown files."
----
-
-# Frontmatter
-
-Every Markdown (`.md`) file that `docmd` processes **must** begin with YAML frontmatter. Frontmatter is a block of YAML (YAML Ain't Markup Language) enclosed by triple-dashed lines (`---`) at the very beginning of your file. It's used to set metadata for each page.
-
-## Basic Structure
-
-```yaml
----
-title: "My Awesome Page Title"
-description: "A concise and informative description for this page, used for SEO and potentially in listings."
-# You can add other custom fields here if needed for your templates or logic
-order: 1 # Example: for custom sorting if you implement such logic
-tags:
-  - guide
-  - advanced
----
-```
-
-## Required Fields
-
-*   **`title`** (String, Required)
-    *   **Purpose:** This is the primary title of the page.
-    *   **Usage:**
-        *   Used for the HTML `<title>` tag (e.g., `Page Title : Site Title`).
-        *   Often used as the main heading (`<h1>`) on the page by default (though themes can customize this).
-        *   Used as the display text for links in the navigation sidebar if the path matches.
-    *   **Example:** `title: "Installation Guide"`
-
-## Optional Fields (Recommended)
-
-*   **`description`** (String, Optional)
-    *   **Purpose:** A brief summary of the page's content.
-    *   **Usage:**
-        *   Used for the HTML `<meta name="description">` tag, which is important for search engine optimization (SEO) and search result snippets.
-    *   **Example:** `description: "Learn how to install and configure the XYZ widget."`
-
-## Custom Fields
-
-You can include any other custom fields in your frontmatter. These fields won't be used by `docmd`'s core functionality directly but can be accessed if you decide to customize EJS templates or write plugins in the future.
-
-Examples of custom fields you *might* add (these are not built-in features):
-
-*   `author`: "Jane Doe"
-*   `date`: "2023-10-26"
-*   `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)
-
-## Page-Specific Behavior Fields
-
-*   **`toc`** (Boolean, Optional)
-    *   **Purpose:** Controls the visibility of the "On This Page" table of contents sidebar.
-    *   **Default:** `true` (TOC is visible if the page has headings).
-    *   **Usage:** Set to `false` to completely hide the TOC sidebar for a specific page. This is useful for landing pages or pages with minimal content.
-    *   **Example:** `toc: false`
-
-## Example Usage
-
-Consider a file named `docs/guides/installation.md`:
-
-```markdown
----
-title: "Installation Steps"
-description: "A step-by-step guide to installing our application on various platforms."
-order: 1
----
-
-# Application Installation
-
-This guide will walk you through installing our application...
-```
-
-In this example:
-*   The browser tab will show "Installation Steps : Your Site Title".
-*   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.

package/docs/content/images.md

@@ -1,205 +0,0 @@
----
-title: "Images"
-description: "Learn how to add and customize images in your docmd documentation"
----
-
-# Images in docmd
-
-Adding images to your documentation enhances visual understanding and makes your content more engaging. This guide covers everything you need to know about using images in docmd.
-
-## Basic Image Syntax
-
-The standard Markdown syntax for images works in docmd:
-
-```markdown
-![Alt text](/path/to/image.jpg "Optional title")
-```
-
-Where:
-- `Alt text` is the alternative text displayed if the image cannot be loaded
-- `/path/to/image.jpg` is the path to your image file
-- `"Optional title"` is a tooltip shown when hovering over the image (optional)
-
-## Image Organization
-
-We recommend organizing your images in a dedicated directory structure:
-
-```
-docs/
-  └── images/
-      ├── getting-started/
-      │   └── installation.png
-      ├── features/
-      │   └── example.jpg
-      └── logo.svg
-```
-
-## Referencing Images
-
-### Relative Paths
-
-Use relative paths to reference images within your documentation:
-
-```markdown
-![Installation Screenshot](../images/getting-started/installation.png)
-```
-
-### Absolute Paths
-
-For images stored in your site's assets directory:
-
-```markdown
-![Logo](/assets/images/logo.png)
-```
-
-## Image Styling
-
-docmd provides several ways to style your images using attribute syntax:
-
-### Image Alignment
-
-You can align images using special class names:
-
-```markdown
-![Left-aligned image](/path/to/image.jpg){.align-left}
-![Center-aligned image](/path/to/image.jpg){.align-center}
-![Right-aligned image](/path/to/image.jpg){.align-right}
-```
-
-### Image Size
-
-Control image dimensions with size classes:
-
-```markdown
-![Small image](/path/to/image.jpg){.size-small}
-![Medium image](/path/to/image.jpg){.size-medium}
-![Large image](/path/to/image.jpg){.size-large}
-```
-
-Or specify custom dimensions:
-
-```markdown
-![Custom size](/path/to/image.jpg){width=300 height=200}
-```
-
-### Image Borders and Shadows
-
-Add borders or shadows to your images:
-
-```markdown
-![Image with border](/path/to/image.jpg){.with-border}
-![Image with shadow](/path/to/image.jpg){.with-shadow}
-![Image with border and shadow](/path/to/image.jpg){.with-border .with-shadow}
-```
-
-Note: Make sure there's a space between multiple classes in the attribute syntax.
-
-### Responsive Images
-
-All images in docmd are responsive by default, automatically scaling to fit their container.
-
-## Image Captions
-
-Add captions to your images using the figure syntax:
-
-```markdown
-<figure>
-  <img src="/path/to/image.jpg" alt="Description of image">
-  <figcaption>This is the caption for the image</figcaption>
-</figure>
-```
-
-## Image Galleries and Lightbox
-
-docmd includes built-in lightbox functionality for image galleries. When users click on an image in a gallery, it opens in a full-screen lightbox view.
-
-### Basic Gallery
-
-Create simple image galleries by grouping images in a grid layout:
-
-```markdown
-<div class="image-gallery">
-  <img src="/path/to/image1.jpg" alt="Image 1">
-  <img src="/path/to/image2.jpg" alt="Image 2">
-  <img src="/path/to/image3.jpg" alt="Image 3">
-</div>
-```
-
-### Gallery with Captions
-
-For galleries with captions, use figure elements inside the gallery:
-
-```markdown
-<div class="image-gallery">
-  <figure>
-    <img src="/path/to/image1.jpg" alt="Image 1">
-    <figcaption>Caption for Image 1</figcaption>
-  </figure>
-  <figure>
-    <img src="/path/to/image2.jpg" alt="Image 2">
-    <figcaption>Caption for Image 2</figcaption>
-  </figure>
-</div>
-```
-
-### Zoom Effect
-
-Add a zoom effect to gallery images when hovering:
-
-```markdown
-<div class="image-gallery zoom">
-  <img src="/path/to/image1.jpg" alt="Image 1">
-  <img src="/path/to/image2.jpg" alt="Image 2">
-</div>
-```
-
-### Individual Lightbox Images
-
-You can also enable lightbox functionality for individual images:
-
-```markdown
-![Image with lightbox](/path/to/image.jpg){.lightbox}
-```
-
-## Image Optimization Best Practices
-
-For optimal performance:
-
-1. **Use appropriate formats**:
-   - JPEG for photographs
-   - PNG for images with transparency
-   - SVG for icons and logos
-   - WebP for better compression (with fallbacks)
-
-2. **Optimize file sizes**:
-   - Compress images before adding them to your documentation
-   - Consider using tools like ImageOptim, TinyPNG, or Squoosh
-
-3. **Provide responsive images**:
-   - Use the HTML `<picture>` element for advanced responsive image scenarios
-
-4. **Specify dimensions**:
-   - Always include width and height attributes to prevent layout shifts
-
-## Examples
-
-### Basic Image
-
-![docmd preview](/assets/images/docmd-preview.png "docmd Documentation Generator")
-
-### Image with Border and Shadow
-
-![preview with styling](/assets/images/docmd-preview.png){.with-border .with-shadow}
-
-### Responsive Image Gallery
-
-<div class="image-gallery">
-  <figure>
-    <img src="/assets/images/docmd-preview.png" alt="Feature 1">
-    <figcaption>Feature One</figcaption>
-  </figure>
-  <figure>
-    <img src="/assets/images/docmd-preview.png" alt="Feature 2">
-    <figcaption>Feature Two</figcaption>
-  </figure>
-</div> 

package/docs/content/index.md

@@ -1,19 +0,0 @@
----
-title: "Content"
-description: "Learn how to write and format content in docmd"
----
-
-# Content in docmd
-
-docmd uses Markdown files to create beautiful documentation. This section covers everything you need to know about writing content:
-
-## Available Guides
-
-- [**Frontmatter**](/content/frontmatter/) - Learn how to add metadata to your pages
-- [**Markdown Syntax**](/content/markdown-syntax/) - Basic and advanced Markdown features
-- [**Images**](/content/images/) - How to add and style images in your documentation
-- [**Mermaid Diagrams**](/content/mermaid/) - Create beautiful diagrams and flowcharts with Mermaid
-- [**Custom Containers**](/content/custom-containers/) - Special content blocks like callouts and cards
-- [**noStyle Pages**](/content/no-style-pages/) - Create custom standalone pages with complete HTML control
-
-Choose a topic from the sidebar to get started.

package/docs/content/markdown-syntax.md

@@ -1,309 +0,0 @@
----
-title: "Markdown Syntax Guide"
-description: "Learn how to use Markdown syntax to format your documentation in docmd."
----
-
-# Markdown Syntax
-
-`docmd` uses `markdown-it` under the hood, which is a highly extensible and standards-compliant Markdown parser. It supports CommonMark syntax by default, along with some useful extensions like GitHub Flavored Markdown (GFM) tables and strikethrough.
-
-## Common Elements
-
-You can use all standard Markdown elements:
-
-*   **Headings:**
-    ```markdown
-    # Heading 1
-    ## Heading 2
-    ### Heading 3
-    ...
-    ###### Heading 6
-    ```
-*   **Paragraphs:** Just type text. Separate paragraphs with a blank line.
-*   **Emphasis:**
-    ```markdown
-    *This text will be italic.*
-    _This will also be italic._
-
-    **This text will be bold.**
-    __This will also be bold.__
-
-    ***This text will be bold and italic.***
-    ```
-*   **Lists:**
-    *   **Unordered:**
-        ```markdown
-        * Item 1
-        * Item 2
-          * Nested Item 2a
-          * Nested Item 2b
-        + Item 3 (using +)
-        - Item 4 (using -)
-        ```
-    *   **Ordered:**
-        ```markdown
-        1. First item
-        2. Second item
-        3. Third item
-           1. Nested ordered item
-        ```
-*   **Links:**
-    ```markdown
-    [Link Text](https://www.example.com)
-    [Link with Title](https://www.example.com "Link Title")
-    [Relative Link to another page](../section/other-page/)
-    ```
-    *Note: For internal links to other documentation pages, use relative paths to the `.md` files. `docmd` will convert these to the correct HTML paths during the build.*
-
-*   **Images:**
-    ```markdown
-    ![Alt text for image](/path/to/your/image.jpg "Optional Image Title")
-    ```
-    *Place images in your `docs/` directory (e.g., `docs/images/`) or a similar assets folder that gets copied to your `site/` output.*
-
-*   **Blockquotes:**
-    ```markdown
-    > This is a blockquote.
-    > It can span multiple lines.
-    ```
-*   **Horizontal Rules:**
-    ```markdown
-    ---
-    ***
-    ___
-    ```
-*   **Inline Code:**
-    ```markdown
-    Use `backticks` for inline code like `variableName`.
-    ```
-
-## Code Blocks & Syntax Highlighting
-
-`docmd` uses `highlight.js` for automatic syntax highlighting of fenced code blocks. Specify the language after the opening triple backticks:
-
-```javascript
-function greet(name) {
-  console.log(`Hello, ${name}!`);
-}
-greet('docmd user');
-```
-
-```python
-def hello():
-    print("Hello from Python!")
-
-hello()
-```
-
-```html
-<div>
-  <p>This is some HTML.</p>
-</div>
-```
-
-```css
-body {
-  font-family: sans-serif;
-  color: #333;
-}
-```
-
-```bash
-npm install -g docmd
-docmd init my-docs
-```
-
-If you don't specify a language, `highlight.js` will attempt to auto-detect it, or it will be rendered as plain preformatted text.
-
-## Tables (GFM Style)
-
-You can create tables using GitHub Flavored Markdown syntax:
-
-```bash
-| Header 1 | Header 2 | Header 3 |
-| :------- | :------: | -------: |
-| Align L  | Center   | Align R  |
-| Cell 1   | Cell 2   | Cell 3   |
-| Cell 4   | Cell 5   | Cell 6   |
-```
-Renders as:
-
-| Header 1 | Header 2 | Header 3 |
-| :------- | :------: | -------: |
-| Align L  | Center   | Align R  |
-| Cell 1   | Cell 2   | Cell 3   |
-| Cell 4   | Cell 5   | Cell 6   |
-
-## Strikethrough (GFM Style)
-
-Wrap text with two tildes (`~~`) for strikethrough:
-```bash
-This is ~~strikethrough~~ text.
-```
-Renders as: This is ~~strikethrough~~ text.
-
-## HTML
-
-Because `markdown-it` is configured with `html: true`, you can embed raw HTML directly in your Markdown files. However, use this sparingly, as it can make your content less portable and harder to maintain.
-
-```html
-<div style="color: blue;">
-  This is a blue div rendered directly from HTML.
-</div>
-```
-
-For most formatting needs, standard Markdown and `docmd`'s [Custom Containers](/content/custom-containers/) should suffice.
-
-# Advanced Markdown Capabilities
-
-Beyond the basic syntax, `docmd` supports a variety of advanced Markdown features to help you create richer documentation.
-
-## Example Callout
-
-::: callout info
-This is a real callout example to test container rendering. Callouts are great for highlighting important information.
-:::
-
-::: callout warning
-**Warning!** Be careful when using advanced features, ensure they are properly documented.
-:::
-
-## GFM (GitHub Flavored Markdown)
-
-docmd supports GitHub Flavored Markdown extensions including:
-
-- **Task Lists** - Create interactive checklists:
-  ```markdown
-  - [x] Completed task
-  - [ ] Incomplete task
-  - [ ] Another item
-  ```
-  
-  Renders as:
-  - [x] Completed task
-  - [ ] Incomplete task
-  - [ ] Another item
-
-- **Autolinked References** - URL and email addresses are automatically linked:
-  ```markdown
-  Visit https://docmd.mgks.dev for more information.
-  Contact support@example.com for help.
-  ```
-
-- **Emoji** - Use emoji shortcodes:
-  ```markdown
-  I :heart: documentation! :rocket: :smile:
-  ```
-  
-  Renders emoji symbols like: I ❤️ documentation! 🚀 😄
-
-## Custom Attributes (IDs and Classes)
-
-You can add custom IDs and CSS classes to headers, images, and links using curly braces `{}`.
-
-### Custom IDs
-By default, `docmd` generates IDs for headers automatically. You can override this:
-
-```markdown
-## My Header {#custom-id}
-```
-
-### Custom Classes
-Add styling classes to elements:
-
-```markdown
-## Styled Header {.text-center .text-red}
-```
-
-### Links and Buttons
-Create buttons using standard links and classes:
-
-```markdown
-[Download Now](/download){.btn .btn-primary}
-```
-
-### Images
-Control image styling directly:
-
-```markdown
-![Screenshot](image.png){width="100%" .shadow-lg}
-```
-
-## Footnotes
-
-You can add footnotes to your content for references or additional information[^1].
-
-```markdown
-Here's a statement that needs citation[^1].
-
-[^1]: This is the footnote content.
-```
-
-Multiple footnotes can be used throughout your document[^2], and the definitions can be collected at the bottom.
-
-[^1]: This is the first footnote reference.
-[^2]: This is the second footnote with more information.
-
-## Definition Lists
-
-Some Markdown parsers support definition lists:
-
-```markdown
-Term
-: Definition for the term.
-: Another definition for the same term.
-
-Another Term
-: Definition of another term.
-```
-
-Term
-: Definition for the term.
-: Another definition for the same term.
-
-Another Term
-: Definition of another term.
-
-## Abbreviations
-
-You can define abbreviations in your Markdown (depending on plugin support):
-
-```markdown
-*[HTML]: Hyper Text Markup Language
-*[W3C]: World Wide Web Consortium
-
-HTML is defined by the W3C standards.
-```
-
-*[HTML]: Hyper Text Markup Language
-*[W3C]: World Wide Web Consortium
-
-HTML is defined by the W3C standards.
-
-## Math Expressions
-
-If enabled with the appropriate plugins, you can include mathematical expressions using LaTeX syntax:
-
-```markdown
-Inline math: $E=mc^2$
-
-Block math:
-$$
-\frac{d}{dx}e^x = e^x
-$$
-```
-
-## Container Extensions
-
-Beyond standard Markdown, docmd provides custom containers for enhanced formatting. 
-These are detailed in the [Custom Containers](/content/custom-containers/) guide, and include:
-
-::: callout info
-Use containers for callouts, cards, and steps to structure your documentation.
-:::
-
-## Conclusion
-
-Markdown provides a powerful yet simple way to write and format documentation. With docmd's extensions and customizations, you can create rich, beautiful documentation that's easy to maintain.
-
-For more examples and practical applications, check the rest of the documentation or browse the source of this page by viewing its Markdown file.