@mgks/docmd 0.1.0 → 0.1.1

package/.github/workflows/publish.yml

@@ -2,7 +2,7 @@ name: Publish Package to NPM and GitHub Packages
 
 on:
   release:
-    types: [created] # Triggers when a new GitHub Release is published
+    types: [created, published] # Triggers when a new GitHub Release is created or published
   workflow_dispatch: # Allows manual triggering for testing
 
 jobs:

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
-  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo.png" alt="docmd logo" width="65" />
+  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo.png" alt="docmd logo" width="70" />
   <br />
-  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/logo-light.png" alt="docmd dark logo" width="200" />
+  <img src="https://github.com/mgks/docmd/blob/main/src/assets/images/docmd-logo-light.png" alt="docmd dark logo" width="180" />
 </p>
 
 <p align="center">

package/bin/docmd.js

@@ -30,10 +30,13 @@ program
   .command('build')
   .description('Build the static site from Markdown files and config.js')
   .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .option('-p, --preserve', 'Preserve existing asset files instead of updating them', false)
   .action(async (options) => {
     try {
       console.log('🚀 Starting build process...');
-      await buildSite(options.config);
+      await buildSite(options.config, { 
+        preserve: options.preserve
+      });
       console.log('✅ Build complete! Site generated in `site/` directory.');
     } catch (error) {
       console.error('❌ Build failed:', error.message);
@@ -46,9 +49,10 @@ program
   .command('dev')
   .description('Start a live preview development server')
   .option('-c, --config <path>', 'Path to config.js file', 'config.js')
+  .option('-p, --preserve', 'Preserve existing asset files instead of updating them', false)
   .action(async (options) => {
     try {
-      await startDevServer(options.config);
+      await startDevServer(options.config, { preserve: options.preserve });
     } catch (error) {
       console.error('❌ Dev server failed:', error.message);
       console.error(error.stack);

package/config.js

@@ -8,11 +8,10 @@ module.exports = {
 
   // Logo Configuration
   logo: {
-    light: '/assets/images/logo-light.png', // Path relative to outputDir root
-    dark: '/assets/images/logo-dark.png',   // Path relative to outputDir root
+    light: '/assets/images/docmd-logo-light.png', // Path relative to outputDir root
+    dark: '/assets/images/docmd-logo-dark.png',   // Path relative to outputDir root
     alt: 'docmd Logo',                      // Alt text for the logo
     href: '/',                              // Link for the logo, defaults to site root
-    // height: '30px',                      // Optional: control via CSS is often better
   },
 
   // Directory Configuration
@@ -25,14 +24,14 @@ module.exports = {
     defaultMode: 'light',   // Initial color mode: 'light' or 'dark'
     enableModeToggle: true, // Show UI button to toggle light/dark modes
     customCss: [            // Array of paths to custom CSS files
-      '/assets/css/toc.css', // Custom TOC styles
+      // '/assets/css/custom.css', // Custom TOC styles
     ],
     // options: { /* Future: theme-specific options */ }
   },
 
   // Custom JavaScript Files
   customJs: [               // Array of paths to custom JS files, loaded at end of body
-    // '/assets/js/custom-script.js', // Paths relative to outputDir root
+    '/assets/js/docmd-image-lightbox.js', // Image lightbox functionality
   ],
 
   // Plugins Configuration (Object format)
@@ -78,53 +77,54 @@ module.exports = {
   // Navigation Structure (Sidebar)
   // Icons are kebab-case names from Lucide Icons (https://lucide.dev/)
   navigation: [
-      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true },
-      { title: 'Home', path: '/', icon: 'home' }, // Corresponds to docs/index.md
+      { title: 'Home', path: '/', icon: 'home' },
       {
         title: 'Getting Started',
-        icon: 'rocket', // Lucide: rocket
-        path: '/getting-started/', // Path to the index.md in this folder
+        icon: 'rocket',
+        path: '/getting-started/',
         children: [
-          { title: 'Installation', path: '/getting-started/installation', icon: 'download' }, // Lucide: download
-          { title: 'Basic Usage', path: '/getting-started/basic-usage', icon: 'play' },      // Lucide: play
+          { title: 'Installation', path: '/getting-started/installation', icon: 'download' },
+          { title: 'Basic Usage', path: '/getting-started/basic-usage', icon: 'play' },
         ],
       },
       {
-        title: 'Writing Content',
-        icon: 'pencil', // Lucide: pencil
-        path: '/writing-content/',
+        title: 'Content',
+        icon: 'layout-template',
+        path: '/content/',
         children: [
-          { title: 'Frontmatter', path: '/writing-content/frontmatter', icon: 'file-text' },      // Lucide: file-text
-          { title: 'Markdown Syntax', path: '/writing-content/markdown-syntax', icon: 'code-2' }, // Lucide: code-2
-          { title: 'Custom Containers', path: '/writing-content/custom-containers', icon: 'box' }, // Lucide: box
+          { title: 'Frontmatter', path: '/content/frontmatter', icon: 'file-text' },
+          { title: 'Markdown Syntax', path: '/content/markdown-syntax', icon: 'code-2' },
+          { title: 'Images', path: '/content/images', icon: 'image' },
+          { title: 'Custom Containers', path: '/content/custom-containers', icon: 'box' },
         ],
       },
-      { title: 'Configuration', path: '/configuration', icon: 'settings' }, // Lucide: settings or cog
+      { title: 'Configuration', path: '/configuration', icon: 'settings' },
       {
         title: 'Theming',
-        icon: 'palette', // Lucide: palette
+        icon: 'palette',
         path: '/theming/',
         children: [
-          { title: 'Available Themes', path: '/theming/available-themes', icon: 'layout-grid' }, // Lucide: layout-grid
-          { title: 'Light & Dark Mode', path: '/theming/light-dark-mode', icon: 'sun-moon' },     // Lucide: sun-moon
-          { title: 'Custom CSS & JS', path: '/theming/custom-css-js', icon: 'file-code' },     // Lucide: file-code
-          { title: 'Icons', path: '/theming/icons', icon: 'image' },                        // Lucide: image
+          { title: 'Available Themes', path: '/theming/available-themes', icon: 'layout-grid' },
+          { title: 'Light & Dark Mode', path: '/theming/light-dark-mode', icon: 'sun-moon' },
+          { title: 'Custom CSS & JS', path: '/theming/custom-css-js', icon: 'file-code' },
+          { title: 'Icons', path: '/theming/icons', icon: 'pencil-ruler' },
         ],
       },
       {
         title: 'Plugins',
-        icon: 'puzzle', // Lucide: puzzle
+        icon: 'puzzle',
         path: '/plugins/',
         children: [
-          { title: 'SEO & Meta Tags', path: '/plugins/seo', icon: 'search' },      // Lucide: search
-          { title: 'Analytics', path: '/plugins/analytics', icon: 'bar-chart' },   // Lucide: bar-chart
-          { title: 'Sitemap', path: '/plugins/sitemap', icon: 'map' },             // Lucide: map
+          { title: 'SEO & Meta Tags', path: '/plugins/seo', icon: 'search' },
+          { title: 'Analytics', path: '/plugins/analytics', icon: 'bar-chart' },
+          { title: 'Sitemap', path: '/plugins/sitemap', icon: 'map' },
         ],
       },
-      { title: 'CLI Commands', path: '/cli-commands', icon: 'terminal' }, // Lucide: terminal
-      { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' }, // Lucide: upload-cloud
-      { title: 'Contributing', path: '/contributing', icon: 'users-2' },   // Lucide: users-2
-      // Example of an external link:
+      { title: 'CLI Commands', path: '/cli-commands', icon: 'terminal' },
+      { title: 'Deployment', path: '/deployment', icon: 'upload-cloud' },
+      { title: 'Contributing', path: '/contributing', icon: 'users-2' },
+
+      { title: 'GitHub', path: 'https://github.com/mgks/docmd', icon: 'github', external: true }
   ],
 
   // Footer Configuration

package/docs/cli-commands.md

@@ -41,6 +41,8 @@ The `build` command reads your Markdown files from the source directory (specifi
 
 The output `site/` directory contains all the HTML, CSS, JavaScript, and other assets needed to deploy your documentation.
 
+By default, the build process will update all assets to ensure you have the latest versions from the docmd package. This ensures your site benefits from the latest improvements and fixes.
+
 **Options:**
 
 *   `-c, --config <path>`
@@ -48,6 +50,11 @@ The output `site/` directory contains all the HTML, CSS, JavaScript, and other a
     *   **Description:** Specifies the path to the configuration file. Useful if your config file is not named `config.js` or is not in the project root.
     *   **Example:** `docmd build --config my.docmd.config.js`
 
+*   `-p, --preserve`
+    *   **Default:** `false`
+    *   **Description:** Preserves existing asset files instead of updating them. Use this flag if you've customized any of the default assets and want to keep your modifications.
+    *   **Example:** `docmd build --preserve`
+
 ## `docmd dev`
 
 Starts a local development server with live reloading.
@@ -72,6 +79,12 @@ This provides a fast feedback loop, allowing you to see your changes almost inst
     *   **Default:** `config.js`
     *   **Description:** Specifies the path to the configuration file.
     *   **Example:** `docmd dev --config my.docmd.config.js`
+
+*   `-p, --preserve`
+    *   **Default:** `false`
+    *   **Description:** Preserves existing asset files instead of updating them. Use this flag if you've customized any of the default assets and want to keep your modifications.
+    *   **Example:** `docmd dev --preserve`
+
 *   `-p, --port <port_number>` (Future Option)
     *   **Description:** While not yet implemented, a future version might allow specifying a custom port for the development server. Currently, it defaults to port 3000 or the next available port if 3000 is in use.
 

package/docs/content/images.md

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

@@ -0,0 +1,17 @@
+---
+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
+- [**Custom Containers**](/content/custom-containers) - Special content blocks like callouts and cards
+
+Choose a topic from the sidebar to get started.

package/docs/theming/custom-css-js.md

@@ -35,6 +35,37 @@ module.exports = {
     2.  Place them in a folder within your project (e.g., `my-project/static-assets/css/`).
     3.  Ensure that this folder (or its contents) is copied to the correct location in your `site/` directory during `docmd`'s asset copying process. If `docmd` copies a top-level `assets/` folder from your source, place them there.
 
+## Managing Custom Assets
+
+By default, `docmd` will always update assets to the latest version when you run `build` or `dev` commands. This ensures your site benefits from the latest improvements and fixes.
+
+### Customizing Default Assets
+
+If you want to customize default assets (like theme CSS files or scripts):
+
+1. First, build your site normally to generate all assets:
+   ```bash
+   docmd build
+   ```
+
+2. Modify the generated files in the `site/assets` directory as needed.
+
+3. When rebuilding, use the `--preserve` flag to keep your customized files:
+   ```bash
+   docmd build --preserve
+   ```
+
+This approach allows you to:
+- Always get the latest assets when you want them (default behavior)
+- Preserve your customizations when needed (with `--preserve`)
+- Easily see which files are being preserved during the build process
+
+The `--preserve` flag works with both `build` and `dev` commands:
+```bash
+# Preserve custom assets during development
+docmd dev --preserve
+```
+
 **Use Cases for Custom CSS:**
 *   **Overriding CSS Variables:** The `default` theme uses CSS variables extensively. You can redefine these in your custom CSS.
     ```css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgks/docmd",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Generate beautiful, lightweight static documentation sites directly from your Markdown files. Zero clutter, just content.",
   "main": "src/index.js",
   "bin": {
@@ -35,6 +35,7 @@
   },
   "homepage": "https://github.com/mgks/docmd#readme",
   "dependencies": {
+    "@mgks/docmd": "^0.1.0",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
     "ejs": "^3.1.9",
@@ -44,6 +45,7 @@
     "highlight.js": "^11.11.1",
     "lucide-static": "^0.508.0",
     "markdown-it": "^14.1.0",
+    "markdown-it-attrs": "^4.3.1",
     "markdown-it-container": "^4.0.0",
     "ws": "^8.17.0"
   },