docyard 0.3.0 → 0.4.0

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

@@ -1,4 +1,5 @@
 // Docyard Theme JavaScript
+// Handles dark/light theme toggling
 
 (function() {
   'use strict';
@@ -17,193 +18,9 @@
     });
   }
 
-  function initMobileMenu() {
-    const toggle = document.querySelector('.secondary-header-menu');
-    const sidebar = document.querySelector('.sidebar');
-    const overlay = document.querySelector('.mobile-overlay');
-
-    if (!toggle || !sidebar || !overlay) return;
-
-    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);
-    });
-  }
-
-  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() {
-      initThemeToggle();
-      initMobileMenu();
-      initAccordion();
-      initSidebarScroll();
-      initScrollBehavior();
-    });
+    document.addEventListener('DOMContentLoaded', initThemeToggle);
   } else {
     initThemeToggle();
-    initMobileMenu();
-    initAccordion();
-    initSidebarScroll();
-    initScrollBehavior();
   }
 })();

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

@@ -1,20 +1,42 @@
 # Docyard Configuration
-# All fields are optional - remove what you don't need
+# Documentation: https://github.com/yourusername/docyard
 
+# Site Information
 site:
   title: "My Documentation"
   description: "Documentation for my project"
 
-# Custom branding (paths relative to docs/ directory, or use URLs)
+# Custom Branding (Optional)
+# Paths relative to docs/ directory, or use URLs for CDN-hosted assets
 branding:
-  # logo: "assets/logo.svg"              # or "https://cdn.example.com/logo.svg" (defaults to Docyard logo)
-  # logo_dark: "assets/logo-dark.svg"    # Dark mode logo (optional)
-  # favicon: "assets/favicon.svg"        # Browser tab icon (defaults to Docyard favicon)
+  # 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 (true/false)
-  #   title: true                         # Show site title (true/false)
+  #   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"
-  base_url: "/"
-  clean: true
+  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

@@ -25,7 +25,7 @@
   <!-- Primary Header -->
   <header class="header">
     <div class="header-content">
-      <a href="/" class="header-logo">
+      <a href="<%= link_path('/') %>" class="header-logo">
         <% if @display_logo %>
         <div class="site-logo-container">
           <% if @logo %>

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!
+:::