docyard 0.2.0 → 0.3.0

data/lib/docyard/templates/markdown/components/callouts.md.erb

@@ -0,0 +1,204 @@
+# Callouts
+
+Docyard supports beautiful callouts (also known as admonitions) to highlight important information in your documentation. Callouts support both VitePress-style syntax and GitHub-style alerts.
+
+## Callout Types
+
+There are 5 callout types, each with a distinct color and icon:
+
+### Note (Blue)
+
+Use **note** callouts for neutral, informational content that provides additional context.
+
+::: note
+This is a note callout with the default title.
+:::
+
+::: note Custom Title
+You can customize the title of any callout type.
+:::
+
+### Tip (Green)
+
+Use **tip** callouts for helpful advice, best practices, or pro tips.
+
+::: tip
+This is a helpful tip to improve your documentation.
+:::
+
+::: tip Best Practice
+Always include callouts to make important information stand out!
+:::
+
+### Important (Purple)
+
+Use **important** callouts for crucial information that requires special attention.
+
+::: important
+This information is important and should not be overlooked.
+:::
+
+::: important Critical Information
+Pay special attention to this section of the documentation.
+:::
+
+### Warning (Orange)
+
+Use **warning** callouts when users need to be careful or aware of potential issues.
+
+::: warning
+Be careful when following these instructions as they may affect your system.
+:::
+
+::: warning Potential Issues
+Make sure to backup your data before proceeding with this operation.
+:::
+
+### Danger (Red)
+
+Use **danger** callouts for critical warnings about dangerous operations or severe consequences.
+
+::: danger
+This operation is dangerous and may result in data loss. Proceed with extreme caution.
+:::
+
+::: danger Do Not Do This
+Never run this command in production without thorough testing!
+:::
+
+## GitHub-Style Alerts
+
+Docyard also supports GitHub-style alert syntax for compatibility with existing documentation.
+
+> [!NOTE]
+> This is a GitHub-style note alert. It renders exactly the same as the VitePress syntax.
+
+> [!TIP]
+> GitHub alerts are automatically converted to beautifully styled callouts!
+
+> [!IMPORTANT]
+> You can use either syntax - both produce the same visual result.
+
+> [!WARNING]
+> GitHub-style warnings work just like VitePress warnings.
+
+> [!CAUTION]
+> The CAUTION type maps to the danger callout style.
+
+## Rich Content Support
+
+Callouts support all markdown features, making them extremely versatile.
+
+### Inline Formatting
+
+::: note
+Callouts support **bold text**, *italic text*, `inline code`, and [links](https://github.com).
+:::
+
+### Lists
+
+::: tip Key Features
+Here are the main benefits of using callouts:
+
+- Improved readability
+- Visual hierarchy
+- Better user engagement
+- Accessible design with ARIA roles
+- Dark mode support
+:::
+
+### Code Blocks
+
+::: important
+You can include code examples inside callouts:
+
+```ruby
+class Docyard::CalloutProcessor
+  def self.preprocess(markdown)
+    # Process callout syntax
+  end
+end
+```
+
+The code will be syntax-highlighted just like regular code blocks.
+:::
+
+### Multi-Paragraph Content
+
+::: warning
+This callout contains multiple paragraphs to demonstrate complex content.
+
+Each paragraph is properly spaced and rendered. You can include as much content as you need.
+
+You can even mix paragraphs with other elements like lists or code blocks.
+:::
+
+### Nested Content
+
+::: tip Advanced Usage
+Callouts can contain complex nested structures:
+
+1. **First step**: Install Docyard
+   ```bash
+   gem install docyard
+   ```
+
+2. **Second step**: Initialize your project
+   ```bash
+   docyard init my-docs
+   ```
+
+3. **Third step**: Start the development server
+   ```bash
+   docyard serve
+   ```
+
+And you're ready to go!
+:::
+
+## Multiple Callouts
+
+You can use multiple callouts in sequence to create rich, informative documentation:
+
+::: note Prerequisites
+Before starting this tutorial, make sure you have Ruby 3.0+ installed.
+:::
+
+::: tip
+Use `ruby --version` to check your Ruby version.
+:::
+
+::: warning
+If you're using a Ruby version older than 3.0, some features may not work correctly.
+:::
+
+## Accessibility
+
+All callouts include proper ARIA roles for screen readers:
+
+- Note, Tip, and Important callouts use `role="note"`
+- Warning and Danger callouts use `role="alert"` for higher priority
+
+## Dark Mode
+
+Callouts automatically adapt to dark mode with enhanced colors and subtle glow effects for better visibility.
+
+## Comparison Table
+
+| Callout Type | Color  | Icon            | When to Use                          |
+|--------------|--------|-----------------|--------------------------------------|
+| Note         | Blue   | Info            | General information, context         |
+| Tip          | Green  | Lightbulb       | Helpful advice, best practices       |
+| Important    | Purple | Warning Circle  | Critical information, key points     |
+| Warning      | Orange | Warning         | Caution, potential issues            |
+| Danger       | Red    | Siren           | Severe warnings, dangerous operations|
+
+## Examples in Action
+
+::: note Documentation Tip
+Throughout the Docyard documentation, you'll see callouts used to highlight key information, provide helpful tips, and warn about potential issues.
+:::
+
+::: tip
+Try creating your own callouts in your documentation to see how they improve readability and user engagement!
+:::

data/lib/docyard/templates/markdown/components/icons.md.erb

@@ -0,0 +1,125 @@
+# Icons
+
+Docyard includes 24 essential Phosphor icons that work seamlessly in your markdown. Icons automatically match your text size and inherit colors from the surrounding content.
+
+## Basic Usage
+
+Simply type `:icon-name:` anywhere in your markdown:
+
+```markdown
+:check: Task completed
+:warning: Important note
+:rocket-launch: Ready to launch
+```
+
+Result:
+
+:check: Task completed
+
+:warning: Important note
+
+:rocket-launch: Ready to launch
+
+## Icon Weights
+
+Phosphor icons come in 6 different weights. Specify the weight after the icon name:
+
+```markdown
+:heart: Regular (default)
+:heart:bold: Bold weight
+:heart:fill: Filled version
+:heart:light: Light weight
+:heart:thin: Thin weight
+:heart:duotone: Duotone style
+```
+
+Result:
+
+:heart: Regular · :heart:bold: Bold · :heart:fill: Fill · :heart:light: Light · :heart:thin: Thin · :heart:duotone: Duotone
+
+## Common Use Cases
+
+### Feature Lists
+
+```markdown
+:check: Zero configuration
+:lightning: Hot reload
+:code: Syntax highlighting
+:moon-stars: Dark mode support
+:package: Ruby-native
+```
+
+:check: Zero configuration
+
+:lightning: Hot reload
+
+:code: Syntax highlighting
+
+:moon-stars: Dark mode support
+
+:package: Ruby-native
+
+### Callouts and Alerts
+
+```markdown
+:warning: **Warning:** Make sure to back up your data first.
+
+:info: **Tip:** You can combine icons with any markdown formatting.
+
+:x: **Error:** Connection failed. Please try again.
+```
+
+:warning: **Warning:** Make sure to back up your data first.
+
+:info: **Tip:** You can combine icons with any markdown formatting.
+
+:x: **Error:** Connection failed. Please try again.
+
+### Navigation and Links
+
+```markdown
+:arrow-right: [Next: File Structure](file-structure)
+:arrow-left: [Previous: Installation](../getting-started/installation)
+:link-external: [View on GitHub](https://github.com)
+```
+
+:arrow-right: [Next: File Structure](file-structure)
+
+:arrow-left: [Previous: Installation](../getting-started/installation)
+
+:link-external: [View on GitHub](https://github.com)
+
+## Available Icons
+
+### UI & Actions
+:check: `check` · :x: `x` · :warning: `warning` · :info: `info` · :question: `question` · :copy: `copy`
+
+### Arrows & Navigation
+:arrow-right: `arrow-right` · :arrow-left: `arrow-left` · :arrow-up: `arrow-up` · :arrow-down: `arrow-down`
+
+### Development
+:code: `code` · :terminal: `terminal` · :package: `package` · :github: `github`
+
+### General
+:heart: `heart` · :star: `star` · :rocket-launch: `rocket-launch` · :lightning: `lightning`
+
+### Theme
+:sun: `sun` · :moon-stars: `moon-stars`
+
+### Links
+:link-external: `link-external`
+
+## Tips
+
+1. **Size Matching**: Icons automatically scale to match surrounding text size (headings, paragraphs, etc.)
+2. **Color Inheritance**: Icons use `currentColor`, so they inherit text color from parent elements
+3. **Unknown Icons**: If an icon doesn't exist, the `:icon-name:` syntax stays as plain text
+4. **Code Blocks**: Icon syntax inside code blocks won't be processed (as expected)
+
+## More Icons
+
+Docyard ships with 24 essential icons by default, each available in 6 weights (regular, bold, fill, light, thin, duotone). The full Phosphor icon set includes 1000+ icons at [phosphoricons.com](https://phosphoricons.com), but Docyard includes only the most commonly needed icons to keep the gem lightweight.
+
+## Attribution
+
+Icons provided by [Phosphor Icons](https://phosphoricons.com) under the MIT License.