docyard 0.2.0 → 0.3.0

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

@@ -0,0 +1,686 @@
+# Code Tabs
+
+Docyard supports interactive code tabs to display multiple code examples or package manager installation commands in a space-efficient way. Users can switch between tabs, and their preference is automatically saved.
+
+## Basic Usage
+
+### Package Manager Installation
+
+The most common use case is showing installation commands for different package managers:
+
+:::tabs
+== npm
+```bash
+npm install docyard
+```
+
+== yarn
+```bash
+yarn add docyard
+```
+
+== pnpm
+```bash
+pnpm add docyard
+```
+
+== bun
+```bash
+bun add docyard
+```
+:::
+
+## Tab Icons
+
+Tabs automatically display icons to make them more visually distinctive and easier to scan. Icons can be specified manually or detected automatically from code blocks.
+
+### Auto-Detected Icons
+
+When your tab contains a code block, Docyard automatically detects the programming language and displays the appropriate icon:
+
+:::tabs
+== JavaScript
+```javascript
+const greeting = "Hello, World!";
+console.log(greeting);
+```
+
+== Python
+```python
+greeting = "Hello, World!"
+print(greeting)
+```
+
+== Ruby
+```ruby
+greeting = "Hello, World!"
+puts greeting
+```
+
+== Go
+```go
+package main
+import "fmt"
+
+func main() {
+    fmt.Println("Hello, World!")
+}
+```
+:::
+
+The following languages are automatically detected and display their brand icons:
+
+| Language | Aliases | Icon Source |
+|----------|---------|-------------|
+| JavaScript | `js` | Simple Icons |
+| TypeScript | `ts` | Simple Icons |
+| Python | `py` | Simple Icons |
+| Ruby | `rb` | Simple Icons |
+| Go | `golang` | Simple Icons |
+| Rust | `rs` | Simple Icons |
+| PHP | - | Simple Icons |
+| HTML | `html5`, `htm` | Simple Icons |
+| CSS | - | Simple Icons |
+| C | - | Simple Icons |
+| C++ | `cpp`, `cxx`, `c++` | Simple Icons |
+| SQL | - | PostgreSQL icon |
+| Bash | `sh`, `shell` | Simple Icons |
+| Swift | - | Simple Icons |
+| Kotlin | `kt` | Simple Icons |
+| Elixir | `ex` | Simple Icons |
+| Dart | - | Simple Icons |
+| Scala | - | Simple Icons |
+
+### Manual Icons
+
+You can specify a custom icon using the `:icon-name:` syntax at the start of your tab name:
+
+:::tabs
+== :package: npm
+```bash
+npm install docyard
+```
+
+== :cube: yarn
+```bash
+yarn add docyard
+```
+
+== :rocket: Quick Start
+Get started in seconds with our CLI tool.
+
+== :gear: Configuration
+Customize Docyard to fit your needs.
+:::
+
+Manual icons use the [Phosphor Icons](https://phosphoricons.com) library, giving you access to hundreds of beautiful icons.
+
+### Icon Fallback
+
+If a tab doesn't have a manual icon specified and doesn't contain a recognized code block, it will display a generic code icon from Phosphor Icons.
+
+:::tabs
+== Overview
+This tab shows markdown content without a code block, so it gets the default code icon.
+
+== JavaScript
+```javascript
+// This tab auto-detects the JavaScript icon
+console.log("Hello!");
+```
+
+== :star: Featured
+Manual icon takes precedence over auto-detection.
+:::
+
+## Programming Language Examples
+
+Show the same functionality in different programming languages:
+
+:::tabs
+== JavaScript
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+
+console.log(greet('World'));
+```
+
+== TypeScript
+```typescript
+function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+
+console.log(greet('World'));
+```
+
+== Ruby
+```ruby
+def greet(name)
+  "Hello, #{name}!"
+end
+
+puts greet('World')
+```
+
+== Python
+```python
+def greet(name):
+    return f"Hello, {name}!"
+
+print(greet('World'))
+```
+:::
+
+## Framework-Specific Examples
+
+Compare syntax across different frameworks:
+
+:::tabs
+== React
+```jsx
+import { useState } from 'react';
+
+export default function Counter() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+== Vue
+```vue
+<template>
+  <button @click="count++">
+    Count: {{ count }}
+  </button>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const count = ref(0);
+</script>
+```
+
+== Svelte
+```svelte
+<script>
+  let count = 0;
+</script>
+
+<button on:click={() => count++}>
+  Count: {count}
+</button>
+```
+:::
+
+## Configuration Files
+
+Show different configuration formats:
+
+:::tabs
+== JSON
+```json
+{
+  "name": "docyard",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "test": "jest"
+  }
+}
+```
+
+== YAML
+```yaml
+name: docyard
+version: 1.0.0
+main: index.js
+scripts:
+  start: node index.js
+  test: jest
+```
+
+== TOML
+```toml
+name = "docyard"
+version = "1.0.0"
+main = "index.js"
+
+[scripts]
+start = "node index.js"
+test = "jest"
+```
+:::
+
+## Rich Markdown Content
+
+Tabs support all markdown features, not just code blocks:
+
+:::tabs
+== Overview
+# Getting Started
+
+Welcome to Docyard! This tab contains **rich markdown** content.
+
+- Easy to use
+- Fully customizable
+- Dark mode support
+
+Learn more in the [documentation](https://github.com).
+
+== Installation
+Install Docyard using your preferred package manager:
+
+```bash
+gem install docyard
+```
+
+Then initialize a new project:
+
+```bash
+docyard init my-docs
+cd my-docs
+docyard serve
+```
+
+== Configuration
+You can customize Docyard by creating a `docyard.yml` file:
+
+```yaml
+title: My Documentation
+theme: default
+sidebar:
+  - Home
+  - Getting Started
+  - API Reference
+```
+
+See the configuration guide for all available options.
+:::
+
+## Multiple Tab Groups
+
+You can use multiple tab groups in the same document:
+
+### Client Installation
+
+:::tabs
+== npm
+```bash
+npm install @docyard/client
+```
+
+== yarn
+```bash
+yarn add @docyard/client
+```
+:::
+
+### Server Installation
+
+:::tabs
+== npm
+```bash
+npm install @docyard/server
+```
+
+== yarn
+```bash
+yarn add @docyard/server
+```
+:::
+
+## API Comparison
+
+Compare different API approaches:
+
+:::tabs
+== REST API
+```javascript
+// Fetch user data
+fetch('/api/users/123')
+  .then(response => response.json())
+  .then(user => console.log(user));
+
+// Create new user
+fetch('/api/users', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'John Doe' })
+});
+```
+
+== GraphQL
+```graphql
+# Fetch user data
+query GetUser {
+  user(id: "123") {
+    id
+    name
+    email
+  }
+}
+
+# Create new user
+mutation CreateUser {
+  createUser(input: { name: "John Doe" }) {
+    id
+    name
+  }
+}
+```
+
+== gRPC
+```protobuf
+// user.proto
+service UserService {
+  rpc GetUser (GetUserRequest) returns (User);
+  rpc CreateUser (CreateUserRequest) returns (User);
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+}
+```
+:::
+
+## Environment-Specific Code
+
+Show different code for different environments:
+
+:::tabs
+== Development
+```javascript
+const config = {
+  apiUrl: 'http://localhost:3000',
+  debug: true,
+  logLevel: 'verbose',
+  cache: false
+};
+
+// Development-specific logging
+console.log('Running in development mode');
+```
+
+== Production
+```javascript
+const config = {
+  apiUrl: 'https://api.production.com',
+  debug: false,
+  logLevel: 'error',
+  cache: true
+};
+
+// Production optimizations enabled
+```
+
+== Testing
+```javascript
+const config = {
+  apiUrl: 'http://localhost:3001',
+  debug: true,
+  logLevel: 'info',
+  cache: false,
+  mockData: true
+};
+
+// Test environment with mocks
+```
+:::
+
+## Platform-Specific Instructions
+
+Provide instructions for different operating systems:
+
+:::tabs
+== macOS
+Install the required dependencies:
+
+```bash
+brew install ruby
+brew install node
+```
+
+Then install Docyard:
+
+```bash
+gem install docyard
+```
+
+== Linux
+Install the required dependencies:
+
+```bash
+sudo apt-get update
+sudo apt-get install ruby-full nodejs npm
+```
+
+Then install Docyard:
+
+```bash
+sudo gem install docyard
+```
+
+== Windows
+Download and install:
+- [Ruby for Windows](https://rubyinstaller.org/)
+- [Node.js for Windows](https://nodejs.org/)
+
+Then open PowerShell and run:
+
+```powershell
+gem install docyard
+```
+:::
+
+## Database Queries
+
+Compare query syntax across different databases:
+
+:::tabs
+== PostgreSQL
+```sql
+SELECT u.name, COUNT(p.id) as post_count
+FROM users u
+LEFT JOIN posts p ON u.id = p.user_id
+WHERE u.created_at > '2024-01-01'
+GROUP BY u.id, u.name
+ORDER BY post_count DESC
+LIMIT 10;
+```
+
+== MySQL
+```sql
+SELECT u.name, COUNT(p.id) as post_count
+FROM users u
+LEFT JOIN posts p ON u.id = p.user_id
+WHERE u.created_at > '2024-01-01'
+GROUP BY u.id, u.name
+ORDER BY post_count DESC
+LIMIT 10;
+```
+
+== MongoDB
+```javascript
+db.users.aggregate([
+  {
+    $match: {
+      created_at: { $gt: new Date('2024-01-01') }
+    }
+  },
+  {
+    $lookup: {
+      from: 'posts',
+      localField: '_id',
+      foreignField: 'user_id',
+      as: 'posts'
+    }
+  },
+  {
+    $project: {
+      name: 1,
+      post_count: { $size: '$posts' }
+    }
+  },
+  { $sort: { post_count: -1 } },
+  { $limit: 10 }
+]);
+```
+:::
+
+## Testing Frameworks
+
+Show examples for different testing frameworks:
+
+:::tabs
+== Jest
+```javascript
+describe('Calculator', () => {
+  test('adds two numbers', () => {
+    expect(add(2, 3)).toBe(5);
+  });
+
+  test('subtracts two numbers', () => {
+    expect(subtract(5, 3)).toBe(2);
+  });
+});
+```
+
+== RSpec
+```ruby
+RSpec.describe Calculator do
+  describe '#add' do
+    it 'adds two numbers' do
+      expect(calculator.add(2, 3)).to eq(5)
+    end
+  end
+
+  describe '#subtract' do
+    it 'subtracts two numbers' do
+      expect(calculator.subtract(5, 3)).to eq(2)
+    end
+  end
+end
+```
+
+== pytest
+```python
+def test_add():
+    assert add(2, 3) == 5
+
+def test_subtract():
+    assert subtract(5, 3) == 2
+```
+:::
+
+## Advanced Features
+
+### Keyboard Navigation
+
+Tabs are fully keyboard accessible:
+
+- **Tab**: Focus on the tab list
+- **Arrow Left/Right**: Navigate between tabs
+- **Home**: Jump to first tab
+- **End**: Jump to last tab
+- **Enter/Space**: Activate focused tab
+- **Tab** (again): Move to tab panel content
+
+### Persistent Preferences
+
+The tabs component automatically remembers your package manager preference using localStorage. If you select "pnpm" in one tab group, all package manager tab groups will default to "pnpm" on subsequent page loads.
+
+### Accessibility
+
+All tabs include proper ARIA attributes for screen readers:
+
+- `role="tablist"` for the tab container
+- `role="tab"` for each tab button
+- `role="tabpanel"` for each content panel
+- `aria-selected` to indicate active tab
+- `aria-controls` linking tabs to panels
+- `aria-labelledby` linking panels to tabs
+- `aria-hidden` to hide inactive panels
+
+### Dark Mode
+
+Tabs automatically adapt to dark mode with:
+
+- Enhanced contrast for readability
+- Subtle visual indicators
+- Smooth animations (respects `prefers-reduced-motion`)
+
+## Best Practices
+
+::: tip When to Use Tabs
+Use tabs when you need to show:
+- **Alternative implementations** of the same functionality
+- **Different package managers** or installation methods
+- **Multiple programming languages** for the same example
+- **Platform-specific instructions** (OS, frameworks, etc.)
+- **Environment-specific configurations** (dev, prod, test)
+:::
+
+::: warning When Not to Use Tabs
+Avoid using tabs for:
+- **Sequential content** that should be read in order (use numbered steps instead)
+- **Unrelated content** (use separate sections instead)
+- **Single option** (just show the code directly)
+- **Too many tabs** (>6 tabs becomes hard to navigate)
+:::
+
+## Syntax Reference
+
+Basic syntax:
+
+```markdown
+:::tabs
+== Tab Name 1
+Content for tab 1
+
+== Tab Name 2
+Content for tab 2
+
+== Tab Name 3
+Content for tab 3
+:::
+```
+
+### Tab Names
+
+Tab names support:
+- Letters, numbers, and spaces
+- Special characters (e.g., "Node.js", "C++", "C#")
+- Unicode characters
+
+### Content
+
+Each tab can contain:
+- **Code blocks** with syntax highlighting
+- **Markdown formatting** (bold, italic, links)
+- **Lists** (ordered and unordered)
+- **Headings** and paragraphs
+- **Tables** and blockquotes
+- **Images** and other media
+- **Nested markdown** of any complexity
+
+## Examples in Action
+
+::: note
+Throughout the Docyard documentation, you'll see tabs used to provide multiple implementation options, making it easy for users to find exactly what they need for their specific setup.
+:::
+
+::: tip Try It Yourself
+Create your own tabs in your documentation to improve the user experience when showing multiple code examples or alternatives!
+:::