docyard 0.2.0 → 0.4.0

data/lib/docyard/templates/assets/js/theme.js

@@ -1,193 +1,26 @@
 // Docyard Theme JavaScript
+// Handles dark/light theme toggling
 
 (function() {
   'use strict';
 
-  function initMobileMenu() {
-    const toggle = document.querySelector('.secondary-header-menu');
-    const sidebar = document.querySelector('.sidebar');
-    const overlay = document.querySelector('.mobile-overlay');
+  function initThemeToggle() {
+    const toggle = document.querySelector('.theme-toggle');
+    if (!toggle) return;
 
-    if (!toggle || !sidebar || !overlay) return;
+    toggle.addEventListener('click', function() {
+      const html = document.documentElement;
+      const isDark = html.classList.contains('dark');
+      const newTheme = isDark ? 'light' : 'dark';
 
-    function openMenu() {
-      sidebar.classList.add('is-open');
-      overlay.classList.add('is-visible');
-      toggle.setAttribute('aria-expanded', 'true');
-      document.body.style.overflow = 'hidden';
-    }
-
-    function closeMenu() {
-      sidebar.classList.remove('is-open');
-      overlay.classList.remove('is-visible');
-      toggle.setAttribute('aria-expanded', 'false');
-      document.body.style.overflow = '';
-    }
-
-    function toggleMenu() {
-      if (sidebar.classList.contains('is-open')) {
-        closeMenu();
-      } else {
-        openMenu();
-      }
-    }
-
-    toggle.addEventListener('click', toggleMenu);
-    overlay.addEventListener('click', closeMenu);
-
-    document.addEventListener('keydown', function(e) {
-      if (e.key === 'Escape' && sidebar.classList.contains('is-open')) {
-        closeMenu();
-      }
-    });
-
-    sidebar.querySelectorAll('a').forEach(function(link) {
-      link.addEventListener('click', closeMenu);
+      html.classList.toggle('dark', !isDark);
+      localStorage.setItem('theme', newTheme);
     });
   }
 
-  function initAccordion() {
-    const toggles = document.querySelectorAll('.nav-group-toggle');
-
-    toggles.forEach(function(toggle) {
-      toggle.addEventListener('click', function() {
-        const expanded = toggle.getAttribute('aria-expanded') === 'true';
-        const children = toggle.nextElementSibling;
-
-        if (!children || !children.classList.contains('nav-group-children')) {
-          return;
-        }
-
-        toggle.setAttribute('aria-expanded', !expanded);
-        children.classList.toggle('collapsed');
-
-        if (expanded) {
-          children.style.maxHeight = '0';
-        } else {
-          children.style.maxHeight = children.scrollHeight + 'px';
-        }
-      });
-    });
-
-    document.querySelectorAll('.nav-group-children.collapsed').forEach(function(el) {
-      el.style.maxHeight = '0';
-    });
-  }
-
-  function initSidebarScroll() {
-    const scrollContainer = document.querySelector('.sidebar nav');
-    if (!scrollContainer) return;
-
-    const STORAGE_KEY = 'docyard_sidebar_scroll';
-    const savedPosition = sessionStorage.getItem(STORAGE_KEY);
-
-    if (savedPosition) {
-      const position = parseInt(savedPosition, 10);
-      scrollContainer.scrollTop = position;
-
-      setTimeout(function() {
-        scrollContainer.scrollTop = position;
-      }, 100);
-    } else {
-      const activeLink = scrollContainer.querySelector('a.active');
-      if (activeLink) {
-        setTimeout(function() {
-          activeLink.scrollIntoView({
-            behavior: 'instant',
-            block: 'center'
-          });
-        }, 50);
-      }
-    }
-
-    scrollContainer.querySelectorAll('a').forEach(function(link) {
-      link.addEventListener('click', function() {
-        sessionStorage.setItem(STORAGE_KEY, scrollContainer.scrollTop);
-      });
-    });
-
-    let scrollTimeout;
-    scrollContainer.addEventListener('scroll', function() {
-      clearTimeout(scrollTimeout);
-      scrollTimeout = setTimeout(function() {
-        sessionStorage.setItem(STORAGE_KEY, scrollContainer.scrollTop);
-      }, 150);
-    });
-
-    const logo = document.querySelector('.header-logo');
-    if (logo) {
-      logo.addEventListener('click', function() {
-        sessionStorage.removeItem(STORAGE_KEY);
-        scrollContainer.scrollTop = 0;
-      });
-    }
-  }
-
-  function initScrollBehavior() {
-    const header = document.querySelector('.header');
-    const secondaryHeader = document.querySelector('.secondary-header');
-
-    if (!header || !secondaryHeader) return;
-
-    let lastScrollTop = 0;
-    let ticking = false;
-
-    function isMobile() {
-      return window.innerWidth <= 1024;
-    }
-
-    function updateHeaders() {
-      if (!isMobile()) {
-        header.classList.remove('hide-on-scroll');
-        secondaryHeader.classList.remove('shift-up');
-        ticking = false;
-        return;
-      }
-
-      const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-
-      if (scrollTop > lastScrollTop && scrollTop > 100) {
-        header.classList.add('hide-on-scroll');
-        secondaryHeader.classList.add('shift-up');
-      } else if (scrollTop < lastScrollTop) {
-        header.classList.remove('hide-on-scroll');
-        secondaryHeader.classList.remove('shift-up');
-      }
-
-      lastScrollTop = scrollTop <= 0 ? 0 : scrollTop;
-      ticking = false;
-    }
-
-    window.addEventListener('scroll', function() {
-      if (!ticking) {
-        window.requestAnimationFrame(updateHeaders);
-        ticking = true;
-      }
-    });
-
-    window.addEventListener('resize', function() {
-      if (!isMobile()) {
-        header.classList.remove('hide-on-scroll');
-        secondaryHeader.classList.remove('shift-up');
-      }
-    });
-  }
-
-  if ('scrollRestoration' in history) {
-    history.scrollRestoration = 'manual';
-  }
-
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', function() {
-      initMobileMenu();
-      initAccordion();
-      initSidebarScroll();
-      initScrollBehavior();
-    });
+    document.addEventListener('DOMContentLoaded', initThemeToggle);
   } else {
-    initMobileMenu();
-    initAccordion();
-    initSidebarScroll();
-    initScrollBehavior();
+    initThemeToggle();
   }
 })();

data/lib/docyard/templates/assets/logo-dark.svg

@@ -0,0 +1,4 @@
+<svg width="531" height="769" viewBox="0 0 531 769" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M359.643 59.1798C402.213 89.4398 449.713 123.6 502.063 160.99C510.793 167.23 515.873 170.31 519.293 178.05C523.253 187.02 521.733 198.11 515.883 205.77C513.77 208.536 510.93 211.2 507.363 213.76C379.643 305.353 309.413 355.73 296.673 364.89C287.987 371.136 282.07 374.8 278.923 375.88C269.703 379.026 260.263 378.636 250.603 374.71C248.243 373.75 244.497 371.416 239.363 367.71C199.963 339.29 177.32 322.99 171.433 318.81C128.863 288.54 81.3733 254.39 29.0233 216.99C20.2833 210.75 15.2033 207.67 11.7833 199.93C7.82332 190.96 9.34332 179.87 15.1933 172.21C17.3067 169.443 20.1467 166.78 23.7133 164.22C151.433 72.6264 221.663 22.2498 234.403 13.0898C243.09 6.84309 249.007 3.17976 252.153 2.09976C261.373 -1.04691 270.813 -0.656912 280.473 3.26976C282.833 4.22976 286.58 6.56309 291.713 10.2698C331.113 38.6898 353.757 54.9931 359.643 59.1798Z" fill="#DC2626"/>
+<path d="M467.383 298.01C483.943 286.23 505.033 289.93 519.063 303.51C524.457 308.723 528.033 314.713 529.793 321.48C530.433 323.92 530.733 330.946 530.693 342.56C530.647 356.206 530.657 427.233 530.723 555.64C530.723 566.633 530.513 573 530.093 574.74C527.033 587.29 518.333 592.61 506.693 601.06C504.313 602.786 430.877 656.346 286.383 761.74C275.623 769.59 261.793 770.79 250.113 764.36C249.18 763.846 245.86 761.513 240.153 757.36C150.56 692.066 74.8667 637.046 13.0733 592.3C6.70001 587.68 2.65667 581.73 0.943337 574.45C0.316671 571.783 0.00333476 564.803 0.00333476 553.51C-0.00333191 421.323 -4.06895e-06 348.98 0.0133293 336.48C0.0133293 332.84 -0.0766665 327.18 0.783334 323.18C4.59333 305.51 20.1033 293.29 37.4533 291.15C42.9467 290.476 48.8667 291.276 55.2133 293.55C58.28 294.643 63.3533 297.8 70.4333 303.02C75.98 307.113 82.4433 311.78 89.8233 317.02C128.563 344.526 178.703 380.303 240.243 424.35C242.73 426.13 245.853 428.246 249.613 430.7C257.443 435.8 268.453 436.24 277.213 433.14C279.8 432.22 284.54 429.283 291.433 424.33C394.46 350.276 453.11 308.17 467.383 298.01Z" fill="#E5E5E5"/>
+</svg>

data/lib/docyard/templates/assets/logo.svg

@@ -0,0 +1,12 @@
+<svg width="531" height="769" viewBox="0 0 531 769" fill="none" xmlns="http://www.w3.org/2000/svg">
+<defs>
+<style>
+@media (prefers-color-scheme: dark) {
+  path[fill="#1E1E1D"] { fill: #E5E5E5; }
+  path[fill="#AB333D"] { fill: #DC2626; }
+}
+</style>
+</defs>
+<path d="M359.643 59.1798C402.213 89.4398 449.713 123.6 502.063 160.99C510.793 167.23 515.873 170.31 519.293 178.05C523.253 187.02 521.733 198.11 515.883 205.77C513.77 208.536 510.93 211.2 507.363 213.76C379.643 305.353 309.413 355.73 296.673 364.89C287.987 371.136 282.07 374.8 278.923 375.88C269.703 379.026 260.263 378.636 250.603 374.71C248.243 373.75 244.497 371.416 239.363 367.71C199.963 339.29 177.32 322.99 171.433 318.81C128.863 288.54 81.3733 254.39 29.0233 216.99C20.2833 210.75 15.2033 207.67 11.7833 199.93C7.82332 190.96 9.34332 179.87 15.1933 172.21C17.3067 169.443 20.1467 166.78 23.7133 164.22C151.433 72.6264 221.663 22.2498 234.403 13.0898C243.09 6.84309 249.007 3.17976 252.153 2.09976C261.373 -1.04691 270.813 -0.656912 280.473 3.26976C282.833 4.22976 286.58 6.56309 291.713 10.2698C331.113 38.6898 353.757 54.9931 359.643 59.1798Z" fill="#AB333D"/>
+<path d="M467.383 298.01C483.943 286.23 505.033 289.93 519.063 303.51C524.457 308.723 528.033 314.713 529.793 321.48C530.433 323.92 530.733 330.946 530.693 342.56C530.647 356.206 530.657 427.233 530.723 555.64C530.723 566.633 530.513 573 530.093 574.74C527.033 587.29 518.333 592.61 506.693 601.06C504.313 602.786 430.877 656.346 286.383 761.74C275.623 769.59 261.793 770.79 250.113 764.36C249.18 763.846 245.86 761.513 240.153 757.36C150.56 692.066 74.8667 637.046 13.0733 592.3C6.70001 587.68 2.65667 581.73 0.943337 574.45C0.316671 571.783 0.00333476 564.803 0.00333476 553.51C-0.00333191 421.323 -4.06895e-06 348.98 0.0133293 336.48C0.0133293 332.84 -0.0766665 327.18 0.783334 323.18C4.59333 305.51 20.1033 293.29 37.4533 291.15C42.9467 290.476 48.8667 291.276 55.2133 293.55C58.28 294.643 63.3533 297.8 70.4333 303.02C75.98 307.113 82.4433 311.78 89.8233 317.02C128.563 344.526 178.703 380.303 240.243 424.35C242.73 426.13 245.853 428.246 249.613 430.7C257.443 435.8 268.453 436.24 277.213 433.14C279.8 432.22 284.54 429.283 291.433 424.33C394.46 350.276 453.11 308.17 467.383 298.01Z" fill="#1E1E1D"/>
+</svg>

data/lib/docyard/templates/config/docyard.yml.erb

@@ -0,0 +1,42 @@
+# Docyard Configuration
+# Documentation: https://github.com/yourusername/docyard
+
+# Site Information
+site:
+  title: "My Documentation"
+  description: "Documentation for my project"
+
+# Custom Branding (Optional)
+# Paths relative to docs/ directory, or use URLs for CDN-hosted assets
+branding:
+  # logo: "assets/logo.svg"              # Light mode logo
+  # logo_dark: "assets/logo-dark.svg"    # Dark mode logo (optional, falls back to 'logo')
+  # favicon: "assets/favicon.svg"        # Browser tab icon
+  # appearance:
+  #   logo: true                          # Show logo in header
+  #   title: true                         # Show site title in header
+
+# Sidebar Navigation (Optional)
+# Customize the order and organization of your documentation pages
+# Without this, sidebar is auto-generated from docs/ folder structure
+# sidebar:
+#   items:
+#     - installation                     # Simple page reference
+#
+#     - guides:                          # Nested group
+#         text: "User Guides"
+#         icon: "book-open"              # Icon from phosphoricons.com
+#         items:
+#           - markdown-features
+#           - configuration
+#
+#     - text: "GitHub"                   # External link
+#       link: "https://github.com/youruser/yourrepo"
+#       icon: "github-logo"
+#       target: "_blank"
+
+# Build Configuration
+build:
+  output_dir: "dist"      # Output directory for static files
+  base_url: "/"           # Base URL for deployment (e.g., "/docs/" for subdirectory)
+  clean: true             # Clean output directory before building

data/lib/docyard/templates/layouts/default.html.erb

@@ -3,8 +3,19 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta name="description" content="<%= @page_description || 'Documentation' %>">
-  <title><%= @page_title || 'Documentation' %></title>
+  <meta name="description" content="<%= @site_description %>">
+  <title><%= @page_title %> | <%= @site_title %></title>
+  <link rel="icon" href="<%= asset_path(@favicon) %>" type="image/svg+xml">
+
+  <!-- Prevent flash of wrong theme -->
+  <script>
+    (function() {
+      const theme = localStorage.getItem('theme') ||
+                   (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+      document.documentElement.classList.toggle('dark', theme === 'dark');
+    })();
+  </script>
+
   <link rel="stylesheet" href="/assets/css/main.css">
 </head>
 <body>
@@ -14,9 +25,25 @@
   <!-- Primary Header -->
   <header class="header">
     <div class="header-content">
-      <a href="/" class="header-logo">
-        <span class="header-title"><%= @site_title || 'Documentation' %></span>
+      <a href="<%= link_path('/') %>" class="header-logo">
+        <% if @display_logo %>
+        <div class="site-logo-container">
+          <% if @logo %>
+          <img src="<%= asset_path(@logo) %>" alt="<%= @site_title %>" class="site-logo site-logo-light">
+          <% end %>
+          <% if @logo_dark %>
+          <img src="<%= asset_path(@logo_dark) %>" alt="<%= @site_title %>" class="site-logo site-logo-dark">
+          <% else %>
+          <img src="<%= asset_path(@logo) %>" alt="<%= @site_title %>" class="site-logo site-logo-dark">
+          <% end %>
+        </div>
+        <% end %>
+        <% if @display_title %>
+        <span class="header-title"><%= @site_title %></span>
+        <% end %>
       </a>
+
+      <%= render_partial('_theme_toggle') %>
     </div>
   </header>
 
@@ -46,6 +73,7 @@
   </div>
 
   <script src="/assets/js/theme.js"></script>
+  <script src="/assets/js/components.js"></script>
   <script src="/assets/js/reload.js"></script>
 </body>
 </html>

data/lib/docyard/templates/markdown/getting-started/installation.md.erb

@@ -1,43 +1,77 @@
 # Installation
 
-Learn how to install Docyard on your system.
+Get your documentation site up and running in minutes.
 
 ## Prerequisites
 
-- Ruby 3.2 or higher
-- Bundler (recommended)
+::: note Requirements
+- Ruby 3.0 or higher
+- Bundler (optional, for Gemfile-based projects)
+:::
 
-## Install via RubyGems
+Check your Ruby version:
 
 ```bash
-gem install docyard
+ruby --version
 ```
 
+## Install Docyard
 
-## Install via Bundler
+:::tabs
+== Gem Install
+```bash
+gem install docyard
+```
 
-Add to your Gemfile:
+== Bundler
+Add to your `Gemfile`:
 
 ```ruby
 gem 'docyard'
 ```
 
-
-Then run:
+Then install:
 
 ```bash
 bundle install
 ```
+:::
 
 ## Verify Installation
 
+Check that Docyard was installed successfully:
+
 ```bash
-docyard --version
+docyard version
 ```
 
+## Quick Start
+
+Initialize a new documentation project:
+
+```bash
+# Create new project
+docyard init
+
+# Start development server
+docyard serve
+```
+
+Visit [http://localhost:4200](http://localhost:4200) to see your documentation.
+
+## Available Commands
 
-You should see the version number printed to your terminal.
+| Command | Description |
+|---------|-------------|
+| `docyard init` | Initialize a new documentation project |
+| `docyard serve` | Start development server with hot reload |
+| `docyard build` | Build static site for production |
+| `docyard preview` | Preview production build locally |
 
 ## Next Steps
 
-Now that Docyard is installed, head over to the [Quick Start Guide](quick-start) to create your first documentation site.
+::: tip What's Next?
+- Explore [Markdown Features](../guides/markdown-features) to see what you can do
+- Learn about [Configuration](../guides/configuration) options
+- Start writing your documentation!
+:::

data/lib/docyard/templates/markdown/guides/configuration.md.erb

@@ -0,0 +1,202 @@
+# Configuration
+
+Customize your documentation site with `docyard.yml`.
+
+## Getting Started
+
+Docyard works without any configuration, but you can customize it by creating a `docyard.yml` file in your project root.
+
+::: tip
+The `docyard init` command creates a `docyard.yml` file with helpful examples.
+:::
+
+## Basic Configuration
+
+```yaml
+site:
+  title: "My Documentation"
+  description: "Documentation for my project"
+```
+
+## Branding
+
+### Custom Logo
+
+Add your own logo:
+
+```yaml
+branding:
+  logo: "assets/logo.svg"           # Light mode logo
+  logo_dark: "assets/logo-dark.svg" # Dark mode logo (optional)
+  favicon: "assets/favicon.svg"      # Browser tab icon
+```
+
+::: note File Paths
+- Paths are relative to the `docs/` directory
+- Or use full URLs: `https://cdn.example.com/logo.svg`
+- Supported formats: SVG, PNG, JPG
+:::
+
+### Logo Visibility
+
+Control what appears in the header:
+
+```yaml
+branding:
+  appearance:
+    logo: true   # Show/hide logo
+    title: true  # Show/hide site title
+```
+
+## Sidebar Navigation
+
+Customize the sidebar structure and order:
+
+```yaml
+sidebar:
+  items:
+    # Simple page reference
+    - installation
+
+    # Page with custom text
+    - quick-start:
+        text: "Quick Start Guide"
+
+    # Page with icon
+    - configuration:
+        text: "Configuration"
+        icon: "gear"
+
+    # Nested group
+    - guides:
+        text: "User Guides"
+        icon: "book-open"
+        items:
+          - markdown-features
+          - customization
+
+    # External link
+    - text: "GitHub"
+      link: "https://github.com/yourusername/yourproject"
+      icon: "github-logo"
+      target: "_blank"
+```
+
+::: tip Icons
+Browse available icons at [phosphoricons.com](https://phosphoricons.com). Just use the icon name (e.g., `rocket-launch`, `book-open`).
+:::
+
+### Collapsible Groups
+
+Control whether groups start expanded or collapsed:
+
+```yaml
+sidebar:
+  items:
+    - api:
+        text: "API Reference"
+        collapsed: true  # Start collapsed
+        items:
+          - authentication
+          - endpoints
+          - errors
+```
+
+## Build Configuration
+
+Configure the build output:
+
+```yaml
+build:
+  output_dir: "dist"      # Output directory for built site
+  base_url: "/"           # Base URL for deployment
+  clean: true             # Clean output directory before building
+```
+
+### Base URL
+
+Set the base URL for subdirectory deployments:
+
+```yaml
+build:
+  base_url: "/docs/"  # For example.com/docs/
+```
+
+::: warning Base URL
+If deploying to a subdirectory, make sure base_url matches your deployment path. Otherwise assets won't load correctly.
+:::
+
+## Complete Example
+
+Here's a full configuration file:
+
+```yaml
+site:
+  title: "Acme API Documentation"
+  description: "Official API documentation for Acme"
+
+branding:
+  logo: "assets/logo.svg"
+  logo_dark: "assets/logo-dark.svg"
+  favicon: "assets/favicon.svg"
+  appearance:
+    logo: true
+    title: true
+
+sidebar:
+  items:
+    - index
+
+    - getting-started:
+        text: "Getting Started"
+        icon: "rocket-launch"
+        items:
+          - installation
+          - authentication
+          - quick-start
+
+    - guides:
+        text: "Guides"
+        icon: "book-open"
+        items:
+          - making-requests
+          - error-handling
+          - rate-limiting
+
+    - api:
+        text: "API Reference"
+        icon: "code"
+        collapsed: false
+        items:
+          - users
+          - products
+          - orders
+
+    - text: "GitHub"
+      link: "https://github.com/acme/api"
+      icon: "github-logo"
+      target: "_blank"
+
+build:
+  output_dir: "dist"
+  base_url: "/api/"
+  clean: true
+```
+
+## Configuration Tips
+
+::: tip Best Practices
+1. **Start simple** - Add configuration as you need it
+2. **Use icons consistently** - Pick a set and stick with it
+3. **Organize logically** - Group related pages together
+4. **Test base_url** - Preview with `docyard preview` before deploying
+5. **Keep it maintainable** - Don't over-configure
+:::
+
+## Next Steps
+
+::: note
+- Learn about [markdown features](markdown-features)
+- Check the [installation guide](../getting-started/installation)
+- Start customizing your site!
+:::