docyard 0.1.0 → 0.3.0

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

@@ -0,0 +1,202 @@
+---
+title: Configuration
+---
+
+# Configuration
+
+Docyard uses convention over configuration. You can start using Docyard without any configuration file - it just works!
+
+## Optional Configuration
+
+Create a `docyard.yml` file in your project root to customize your documentation site.
+
+```yaml
+site:
+  title: "My Documentation"
+  description: "Documentation for my project"
+
+build:
+  output_dir: "dist"
+  base_url: "/"
+```
+
+## Configuration Reference
+
+### Site Settings
+
+Configure your site metadata and branding.
+
+#### `site.title`
+
+The title of your documentation site. Shown in the browser tab and header.
+
+- **Type:** String
+- **Default:** `"Documentation"`
+
+```yaml
+site:
+  title: "My Project Docs"
+```
+
+#### `site.description`
+
+Meta description for SEO and social sharing.
+
+- **Type:** String
+- **Default:** `""`
+
+```yaml
+site:
+  description: "Complete documentation for My Project"
+```
+
+#### `site.logo`
+
+Path to your logo image. Displayed in the site header.
+
+- **Type:** String (file path)
+- **Default:** None
+- **Supported formats:** SVG, PNG, JPG
+
+```yaml
+site:
+  logo: "docs/assets/logo.svg"
+```
+
+::: tip
+Use SVG format for your logo for best quality at all screen sizes.
+:::
+
+#### `site.logo_dark`
+
+Optional dark mode variant of your logo.
+
+- **Type:** String (file path)
+- **Default:** None
+
+```yaml
+site:
+  logo: "docs/assets/logo.svg"
+  logo_dark: "docs/assets/logo-dark.svg"
+```
+
+#### `site.favicon`
+
+Path to your favicon.
+
+- **Type:** String (file path)
+- **Default:** None
+- **Supported formats:** `.ico`, `.png`
+
+```yaml
+site:
+  favicon: "docs/assets/favicon.ico"
+```
+
+### Build Settings
+
+Configure static site generation.
+
+#### `build.output_dir`
+
+Directory where the built site will be generated.
+
+- **Type:** String
+- **Default:** `"dist"`
+- **Note:** Cannot contain slashes
+
+```yaml
+build:
+  output_dir: "dist"  # or "_site", "public", etc.
+```
+
+#### `build.base_url`
+
+Base URL for your site. Important for subdirectory deployments.
+
+- **Type:** String
+- **Default:** `"/"`
+- **Note:** Must start with `/`
+
+```yaml
+# For root deployment
+build:
+  base_url: "/"
+
+# For GitHub Pages project site
+build:
+  base_url: "/my-repo/"
+```
+
+::: important
+Set `base_url` correctly for subdirectory deployments (like GitHub Pages project sites) or your assets won't load correctly.
+:::
+
+#### `build.clean`
+
+Whether to clean the output directory before building.
+
+- **Type:** Boolean
+- **Default:** `true`
+
+```yaml
+build:
+  clean: true  # Recommended
+```
+
+## Examples
+
+### Basic Configuration
+
+Minimal config with just a custom title:
+
+```yaml
+site:
+  title: "Acme Documentation"
+```
+
+### Full Branding
+
+Complete branding with logo and favicon:
+
+```yaml
+site:
+  title: "Acme Inc."
+  description: "API documentation for Acme services"
+  logo: "docs/assets/logo.svg"
+  logo_dark: "docs/assets/logo-dark.svg"
+  favicon: "docs/assets/favicon.ico"
+```
+
+### GitHub Pages Deployment
+
+Configuration for GitHub Pages subdirectory:
+
+```yaml
+site:
+  title: "My Project"
+
+build:
+  base_url: "/my-repo/"
+```
+
+### Custom Output Directory
+
+Using a different output directory:
+
+```yaml
+build:
+  output_dir: "public"
+  base_url: "/"
+```
+
+## No Configuration Required
+
+If you don't create a `docyard.yml` file, Docyard will work with sensible defaults:
+
+- Site title: `"Documentation"`
+- Output directory: `dist/`
+- Base URL: `/`
+- Clean build: `true`
+
+This means you can run `docyard serve` immediately after `docyard init` without any additional configuration!

data/lib/docyard/templates/markdown/core-concepts/file-structure.md.erb

@@ -0,0 +1,61 @@
+# File Structure
+
+Understanding how Docyard organizes your documentation.
+
+## Basic Structure
+
+```bash
+docs/
+├── index.md              # Home page
+├── getting-started/      # Section folder
+│   ├── introduction.md
+│   └── quick-start.md
+└── guides/              # Another section
+    └── tutorial.md
+```
+
+## Navigation Rules
+
+- **Folders become sections** in the sidebar navigation
+- **Files become pages** within those sections
+- Files are sorted alphabetically
+- `index.md` in the root is your home page
+
+## File Naming
+
+File names are automatically converted to page titles:
+
+- `quick-start.md` → "Quick Start"
+- `api-reference.md` → "Api Reference"
+- `getting_started.md` → "Getting Started"
+
+## Custom Titles
+
+Override the auto-generated title using an H1 heading:
+
+```markdown
+# Custom Page Title
+
+Your content here...
+```
+
+## Hidden Files
+
+Files and folders starting with `_` or `.` are ignored:
+
+- `_draft.md` - Not included
+- `.notes.md` - Not included
+- `published.md` - Included
+
+## Nested Sections
+
+You can nest folders to create sub-sections:
+
+```bash
+docs/
+└── api/
+    ├── classes/
+    │   └── generator.md
+    └── modules/
+        └── utils.md
+```

data/lib/docyard/templates/markdown/core-concepts/markdown.md.erb

@@ -0,0 +1,90 @@
+# Markdown Support
+
+Docyard supports GitHub Flavored Markdown with syntax highlighting.
+
+## Headings
+
+```markdown
+# H1 Heading
+## H2 Heading
+### H3 Heading
+```
+
+
+## Text Formatting
+
+**Bold text** with `**bold**`
+*Italic text* with `*italic*`
+~~Strikethrough~~ with `~~strikethrough~~`
+
+## Lists
+
+Unordered lists:
+
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested
+
+Ordered lists:
+
+1. First step
+2. Second step
+3. Third step
+
+## Code
+
+Inline code: `const x = 42`
+
+Code blocks with syntax highlighting:
+
+```ruby
+class DocumentationGenerator
+  def initialize(title)
+    @title = title
+  end
+
+  def build
+    puts "Building #{@title}..."
+  end
+end
+```
+
+```javascript
+function generateDocs(title) {
+  console.log(`Building ${title}...`);
+  return { success: true };
+}
+```
+
+
+## Tables
+
+| Feature | Status | Priority |
+|---------|--------|----------|
+| Sidebar | Done | High |
+| Search | Planned | Medium |
+| Dark Mode | Planned | High |
+
+## Links
+
+[External link](https://github.com)
+[Internal link](file-structure)
+[Link to section](../getting-started/installation)
+
+## Blockquotes
+
+> This is a blockquote. Use it to highlight important information or callouts.
+
+## Images
+
+```markdown
+![Alt text](/path/to/image.png)
+```
+
+
+## Task Lists
+
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task

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

@@ -0,0 +1,43 @@
+# Installation
+
+Learn how to install Docyard on your system.
+
+## Prerequisites
+
+- Ruby 3.2 or higher
+- Bundler (recommended)
+
+## Install via RubyGems
+
+```bash
+gem install docyard
+```
+
+
+## Install via Bundler
+
+Add to your Gemfile:
+
+```ruby
+gem 'docyard'
+```
+
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Verify Installation
+
+```bash
+docyard --version
+```
+
+
+You should see the version number printed to your terminal.
+
+## Next Steps
+
+Now that Docyard is installed, head over to the [Quick Start Guide](quick-start) to create your first documentation site.

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

@@ -0,0 +1,30 @@
+# Introduction
+
+Welcome to Docyard - a modern, zero-config documentation generator for Ruby developers.
+
+## What is Docyard?
+
+Docyard turns your Markdown files into beautiful, searchable documentation sites. Write docs in Markdown, and Docyard handles the rest.
+
+## Key Features
+
+- **Auto-generated Navigation** - Sidebar navigation built from your folder structure
+- **Hot Reload** - See changes instantly as you write
+- **GitHub Flavored Markdown** - Full GFM support including tables and task lists
+- **Syntax Highlighting** - 100+ languages powered by Rouge
+- **Zero Configuration** - Works out of the box with sensible defaults
+- **Mobile Responsive** - Looks great on all devices
+
+## Philosophy
+
+Docyard follows these principles:
+
+1. **Simple by default** - No configuration needed to get started
+2. **Markdown-first** - Focus on writing, not tooling
+3. **Beautiful out of the box** - Production-ready styling included
+4. **Developer friendly** - Built by developers, for developers
+
+## Next Steps
+
+- [Install Docyard](installation) to get started
+- Check out the [Quick Start Guide](quick-start) for a 5-minute tutorial

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

@@ -0,0 +1,56 @@
+# Quick Start
+
+Get up and running with Docyard in under 5 minutes.
+
+## 1. Install Docyard
+
+```bash
+gem install docyard
+```
+
+## 2. Initialize Your Project
+
+Create a new documentation project:
+
+```bash
+docyard init
+```
+
+
+This creates a `docs/` folder with sample documentation files.
+
+## 3. Start the Dev Server
+
+```bash
+docyard serve
+```
+
+
+Your documentation will be available at `http://localhost:4200`.
+
+## 4. Edit Your Docs
+
+Open `docs/index.md` and make some changes. The browser will automatically reload to show your changes.
+
+## 5. Organize Your Content
+
+Create folders to organize your documentation:
+
+```bash
+docs/
+├── index.md
+├── getting-started/
+│   ├── introduction.md
+│   └── installation.md
+└── guides/
+    ├── basic-usage.md
+    └── advanced-features.md
+```
+
+
+The sidebar navigation will automatically reflect your folder structure.
+
+## What's Next?
+
+- Learn about [File Structure](../core-concepts/file-structure) conventions
+- Explore [Markdown](../core-concepts/markdown) syntax and features

data/lib/docyard/templates/markdown/index.md.erb

@@ -1,22 +1,86 @@
----
-title: Home
-description: Welcome to your documentation site
----
+# Welcome to Docyard
 
-# Welcome to Docyard!
+A modern, zero-config documentation generator for Ruby developers.
 
-This is your documentation homepage. Edit this file to customize it.
+## Features
 
-## What is Docyard?
-
-Docyard is a beautiful, zero-config documentation generator built with Ruby.
+- **Auto-generated Navigation** - Sidebar built from your folder structure
+- **Hot Reload** - Changes appear instantly while you write
+- **GitHub Flavored Markdown** - Full GFM support with tables and task lists
+- **Syntax Highlighting** - 100+ languages powered by Rouge
+- **Zero Configuration** - Works out of the box with sensible defaults
+- **Mobile Responsive** - Beautiful on desktop, tablet, and mobile
 
 ## Quick Start
 
-1. Edit the markdown files in `docs/`
-2. Run `docyard serve` to preview your site
-3. Run `docyard build` to generate static HTML
+Get up and running in under a minute:
+
+```bash
+# Install
+gem install docyard
+
+# Initialize
+docyard init
+
+# Start dev server
+docyard serve
+```
+
+Visit `http://localhost:4200` to see your docs.
+
+
+## Example Code
+
+Ruby with syntax highlighting:
+
+```ruby
+class DocumentationSite
+  attr_reader :title, :pages
+
+  def initialize(title)
+    @title = title
+    @pages = []
+  end
+
+  def add_page(path, content)
+    pages << { path: path, content: content }
+  end
+
+  def build
+    pages.each { |page| render_page(page) }
+  end
+end
+```
+
+
+JavaScript example:
+
+```javascript
+function buildDocs(config) {
+  const { title, theme } = config;
+  console.log(`Building ${title} with ${theme} theme`);
+  return { success: true };
+}
+```
+
+## Documentation Structure
+
+| Section | Description |
+|---------|-------------|
+| Getting Started | Installation and quick start guide |
+| Core Concepts | Learn about file structure and markdown |
+
+## What's Next?
+
+> Get started by exploring the documentation in the sidebar, or jump straight to the [Quick Start Guide](getting-started/quick-start).
+
+### Learn the Basics
+
+1. [Introduction](getting-started/introduction) - Learn what Docyard can do
+2. [Installation](getting-started/installation) - Install Docyard on your system
+3. [Quick Start](getting-started/quick-start) - Create your first site
 
-## Learn More
+### Understand Core Concepts
 
-Check out the [Getting Started](getting-started.md) guide.
+- [File Structure](core-concepts/file-structure) - How to organize your docs
+- [Markdown](core-concepts/markdown) - Supported markdown features

data/lib/docyard/templates/partials/_callout.html.erb

@@ -0,0 +1,11 @@
+<div class="docyard-callout docyard-callout--<%= @type %>" role="<%= %w[danger warning].include?(@type) ? 'alert' : 'note' %>">
+  <div class="docyard-callout__icon" aria-hidden="true">
+    <%= @icon_svg %>
+  </div>
+  <div class="docyard-callout__content">
+    <div class="docyard-callout__title"><%= @title %></div>
+    <div class="docyard-callout__body">
+      <%= @content_html %>
+    </div>
+  </div>
+</div>

data/lib/docyard/templates/partials/_code_block.html.erb

@@ -0,0 +1,6 @@
+<div class="docyard-code-block">
+  <%= @code_block_html %>
+  <button class="docyard-code-block__copy" aria-label="Copy code to clipboard" data-code="<%= @code_text %>">
+    <%= @copy_icon %>
+  </button>
+</div>

data/lib/docyard/templates/partials/_icon.html.erb

@@ -0,0 +1 @@
+<span class="docyard-icon docyard-icon-<%= @name %>" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><%= @icon_data %></svg></span>

data/lib/docyard/templates/partials/_icon_file_extension.html.erb

@@ -0,0 +1 @@
+<span class="docyard-icon docyard-icon-file-<%= @extension %>" aria-hidden="true"><%= @svg_content %></span>

data/lib/docyard/templates/partials/_icons.html.erb

@@ -0,0 +1,11 @@
+<%# External link icon %>
+<% if @icon_name == :external %>
+  <svg class="external-icon" xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 256 256">
+    <path d="M224,104a8,8,0,0,1-16,0V59.32l-66.33,66.34a8,8,0,0,1-11.32-11.32L196.68,48H152a8,8,0,0,1,0-16h64a8,8,0,0,1,8,8Zm-40,24a8,8,0,0,0-8,8v72H48V80h72a8,8,0,0,0,0-16H48A16,16,0,0,0,32,80V208a16,16,0,0,0,16,16H176a16,16,0,0,0,16-16V136A8,8,0,0,0,184,128Z" />
+  </svg>
+<%# Chevron icon %>
+<% elsif @icon_name == :chevron %>
+  <svg class="nav-group-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor">
+    <path d="M181.66,133.66l-80,80a8,8,0,0,1-11.32-11.32L164.69,128,90.34,53.66a8,8,0,0,1,11.32-11.32l80,80A8,8,0,0,1,181.66,133.66Z"/>
+  </svg>
+<% end %>

data/lib/docyard/templates/partials/_nav_group.html.erb

@@ -0,0 +1,7 @@
+<button class="nav-group-toggle" aria-expanded="true" type="button">
+  <span><%= @title %></span>
+  <%= icon(:chevron) %>
+</button>
+<div class="nav-group-children">
+  <%= @children_html %>
+</div>

data/lib/docyard/templates/partials/_nav_item.html.erb

@@ -0,0 +1,3 @@
+<li>
+  <%= @item_content %>
+</li>

data/lib/docyard/templates/partials/_nav_leaf.html.erb

@@ -0,0 +1 @@
+<a href="<%= @path %>"<%= ' class="active"' if @active %>><%= @title %></a>

data/lib/docyard/templates/partials/_nav_list.html.erb

@@ -0,0 +1,3 @@
+<ul>
+  <%= @list_items %>
+</ul>

data/lib/docyard/templates/partials/_nav_section.html.erb

@@ -0,0 +1,6 @@
+<div class="nav-section">
+  <% if @section_name %>
+    <div class="nav-section-title"><%= @section_name %></div>
+  <% end %>
+  <%= @section_content %>
+</div>

data/lib/docyard/templates/partials/_sidebar.html.erb

@@ -0,0 +1,6 @@
+<aside class="sidebar" role="navigation" aria-label="Documentation navigation">
+  <nav>
+    <%= @nav_content %>
+  </nav>
+  <%= @footer_html %>
+</aside>

data/lib/docyard/templates/partials/_sidebar_footer.html.erb

@@ -0,0 +1,11 @@
+<div class="sidebar-footer">
+  <a href="https://github.com/sanifhimani/docyard"
+     target="_blank"
+     rel="noopener noreferrer"
+     class="sidebar-footer-link">
+    <div class="sidebar-footer-text">
+      <p class="sidebar-footer-title">Built with Docyard</p>
+    </div>
+    <%= icon(:external) %>
+  </a>
+</div>