Comprehensive Markdown Styling Showcase

This document demonstrates the complete capabilities of our enhanced markdown documentation system, showcasing every possible structure and styling option.

Table of Contents

1. Headings
2. Text Formatting
3. Lists
4. Tables
5. Code Examples
6. Blockquotes
7. Links and Media
8. Advanced Elements

Heading Hierarchy Examples

The following demonstrates all six levels of markdown headings:

Example H1 Heading

Example H2 Heading

Example H3 Heading

Example H4 Heading

Example H5 Heading

Example H6 Heading

Text Formatting

Bold text shows strong emphasis and importance.

Italic text provides subtle emphasis and style.

Bold and italic combines both for maximum impact.

Strikethrough text indicates deleted or outdated content.

Inline code highlights technical terms and commands.

Here's some longer inline code: this.is.a.very.long.piece.of.inline.code.that.should.wrap.properly.instead.of.creating.horizontal.scroll.issues.in.our.beautiful.documentation.system

Testing API endpoints: GET /api/v1/organizations/123/projects/456/documents/789/versions/101112/collaborators

Lists

Unordered Lists

• First level item
• Another first level item
  • Second level nested item
  • Another second level item
    • Third level deeply nested
    • Another third level item
• Back to first level

Ordered Lists

1. First numbered item
2. Second numbered item
   1. Nested numbered item
   2. Another nested item
      1. Deeply nested item
      2. Another deep item
3. Back to main sequence

Task Lists

• Completed task with checkmark
• Another completed task
• Pending task to be done
• Another pending task
  • Nested completed subtask
  • Nested pending subtask

Mixed Lists

1. Project Setup
   • Initialize Rails application
   • Configure database
   • Set up CI/CD pipeline
2. Development Phase
   • Create user authentication
   • Build dashboard interface
   • Implement API endpoints

Tables

Basic Table

Advanced Table with Alignment

Complex Data Table

Code Examples

Inline Code

Here's some inline code with proper wrapping. Testing longer examples: ActiveRecord::Base.connection.execute("SELECT * FROM users WHERE created_at > '#{1.week.ago}'").

Ruby Examples

# Service Object Pattern
class DocumentationService
  include Callable
  
  attr_reader :content, :format
  
  def initialize(content:, format: :html)
    @content = content
    @format = format
  end
  
  def call
    case format
    when :html
      render_html
    when :pdf
      render_pdf
    else
      raise ArgumentError, "Unsupported format: #{format}"
    end
  end
  
  private
  
  def render_html
    Kramdown::Document.new(content, {
      syntax_highlighter: 'rouge',
      syntax_highlighter_opts: {
        line_numbers: false,
        default_lang: 'text'
      }
    }).to_html
  end
  
  def render_pdf
    # PDF rendering logic here
  end
end

JavaScript/TypeScript Examples

// Modern ES6+ JavaScript
class MarkdownRenderer {
  constructor(options = {}) {
    this.options = {
      highlightCode: true,
      sanitizeHtml: true,
      ...options
    };
  }
  
  async render(markdown) {
    try {
      const processed = await this.preprocess(markdown);
      const html = this.convertToHtml(processed);
      return this.postprocess(html);
    } catch (error) {
      console.error('Rendering failed:', error);
      throw new RenderingError(error.message);
    }
  }
  
  preprocess(content) {
    return content
      .replace(/\t/g, '  ') // Convert tabs to spaces
      .trim(); // Remove leading/trailing whitespace
  }
}

// Usage example
const renderer = new MarkdownRenderer({
  highlightCode: true,
  sanitizeHtml: true
});

renderer.render(markdownContent)
  .then(html => document.getElementById('output').innerHTML = html)
  .catch(error => console.error(error));

Python Examples

import asyncio
from typing import Dict, List, Optional
from dataclasses import dataclass

@dataclass
class Document:
    """Represents a documentation file."""
    title: str
    content: str
    tags: List[str]
    metadata: Dict[str, str]
    
    def __post_init__(self):
        if not self.title.strip():
            raise ValueError("Title cannot be empty")
    
    @property
    def word_count(self) -> int:
        """Calculate the word count of the document."""
        return len(self.content.split())
    
    def add_tag(self, tag: str) -> None:
        """Add a tag to the document if not already present."""
        if tag not in self.tags:
            self.tags.append(tag)

class DocumentProcessor:
    """Processes and manages documentation files."""
    
    def __init__(self, max_workers: int = 4):
        self.max_workers = max_workers
        self.documents: List[Document] = []
    
    async def process_batch(self, files: List[str]) -> List[Document]:
        """Process multiple files concurrently."""
        semaphore = asyncio.Semaphore(self.max_workers)
        
        async def process_file(file_path: str) -> Document:
            async with semaphore:
                return await self._process_single_file(file_path)
        
        tasks = [process_file(file) for file in files]
        return await asyncio.gather(*tasks)

# Example usage
if __name__ == "__main__":
    processor = DocumentProcessor(max_workers=8)
    files = ["doc1.md", "doc2.md", "doc3.md"]
    
    documents = asyncio.run(processor.process_batch(files))
    print(f"Processed {len(documents)} documents")

SQL Examples

-- Complex query with CTEs and window functions
WITH monthly_stats AS (
  SELECT 
    DATE_TRUNC('month', created_at) as month,
    organization_id,
    COUNT(*) as total_docs,
    SUM(word_count) as total_words,
    AVG(word_count) as avg_words_per_doc
  FROM documents 
  WHERE created_at >= '2024-01-01'
  GROUP BY DATE_TRUNC('month', created_at), organization_id
),
ranked_orgs AS (
  SELECT 
    *,
    ROW_NUMBER() OVER (PARTITION BY month ORDER BY total_docs DESC) as rank,
    LAG(total_docs) OVER (PARTITION BY organization_id ORDER BY month) as prev_month_docs
  FROM monthly_stats
)
SELECT 
  month,
  organization_id,
  total_docs,
  total_words,
  ROUND(avg_words_per_doc, 2) as avg_words_per_doc,
  rank,
  CASE 
    WHEN prev_month_docs IS NULL THEN 'New'
    WHEN total_docs > prev_month_docs THEN 'Growing'
    WHEN total_docs < prev_month_docs THEN 'Declining'
    ELSE 'Stable'
  END as growth_trend
FROM ranked_orgs
WHERE rank <= 10
ORDER BY month DESC, rank ASC;

Shell/Bash Examples

#!/bin/bash

# Advanced deployment script with error handling
set -euo pipefail

readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly APP_NAME="ai-saas-template"
readonly ENVIRONMENT="${1:-staging}"

# Color output
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly NC='\033[0m' # No Color

log() {
  echo -e "${GREEN}[$(date +'%Y-%m-%d %H:%M:%S')]${NC} $*"
}

warn() {
  echo -e "${YELLOW}[WARNING]${NC} $*" >&2
}

error() {
  echo -e "${RED}[ERROR]${NC} $*" >&2
  exit 1
}

cleanup() {
  log "Cleaning up temporary files..."
  rm -rf "${TEMP_DIR:-}"
}

trap cleanup EXIT

main() {
  local temp_dir
  temp_dir=$(mktemp -d)
  readonly TEMP_DIR="$temp_dir"
  
  log "Starting deployment for ${APP_NAME} to ${ENVIRONMENT}"
  
  # Validate environment
  case "$ENVIRONMENT" in
    staging|production)
      log "Valid environment: $ENVIRONMENT"
      ;;
    *)
      error "Invalid environment: $ENVIRONMENT. Must be 'staging' or 'production'"
      ;;
  esac
  
  # Build and deploy
  log "Building Docker image..."
  docker build -t "${APP_NAME}:${ENVIRONMENT}" . || error "Build failed"
  
  log "Running tests..."
  docker run --rm "${APP_NAME}:${ENVIRONMENT}" bundle exec rails test || error "Tests failed"
  
  log "Deployment completed successfully! 🎉"
}

main "$@"

Configuration Files

YAML Configuration

# config/application.yml
defaults: &defaults
  app_name: "AI SaaS Template"
  documentation:
    renderer: kramdown
    syntax_highlighter: rouge
    enable_math: true
    enable_tables: true
  
  features:
    - name: "markdown_processing"
      enabled: true
      options:
        auto_link: true
        line_numbers: false
    - name: "code_highlighting"
      enabled: true
      themes: ["github", "monokai", "solarized"]

development:
  <<: *defaults
  debug: true
  
production:
  <<: *defaults
  debug: false
  documentation:
    cache_enabled: true
    cache_ttl: 3600

JSON Configuration

{
  "name": "ai-saas-template",
  "version": "1.0.0",
  "description": "Modern Rails 8.0 SaaS application with AI capabilities",
  "main": "config.ru",
  "scripts": {
    "dev": "bin/dev",
    "build": "bin/rails assets:precompile",
    "test": "bin/rails test",
    "lint": "rubocop"
  },
  "dependencies": {
    "kramdown": "^2.4.0",
    "rouge": "^4.0.0"
  },
  "engines": {
    "ruby": ">=3.4.0",
    "rails": ">=8.0.0"
  }
}

Blockquotes

Our enhanced blockquote system provides color-coded styles for different message types, each using specific CSS classes to apply appropriate colors, icons, and styling. This creates a professional documentation experience that helps users quickly identify different types of information.

Blockquote Usage Syntax

To apply a specific style to a blockquote, add the CSS class using Kramdown's attribute syntax:

> Your blockquote content here
{: .class-name}

Available Blockquote Types

Information & Notes (Blue)

Classes: .info, .note, .tip
Icons: ℹ️ / 💡 / 📝
Use for: General information, helpful tips, documentation notes

ℹ️ Information

This feature is available in all subscription plans. Check your account settings to verify access.

💡 Helpful Tip

Use keyboard shortcuts to navigate faster: Ctrl+K for search, Ctrl+N for new document.

📝 Note

Remember to save your work frequently when making changes to prevent data loss. The system auto-saves every 30 seconds.

Success & Completion (Green)

Classes: .success, .congratulations, .complete
Icons: ✅ / 🎉
Use for: Successful operations, completed tasks, congratulatory messages

✅ Operation Successful

Your settings have been saved successfully. Changes are now active.

🎉 Congratulations!

You've successfully completed the onboarding process!

✅ Task Complete

All migration scripts have been executed successfully. Database is now up to date with the latest schema.

Warnings & Cautions (Amber)

Classes: .warning, .caution
Icons: ⚠️
Use for: Important warnings, cautionary notices, potential issues

⚠️ Important Warning

This action cannot be undone. Please backup your data before proceeding.

⚠️ Use with Caution

This feature is in beta. Report any issues you encounter.

Important & Attention (Orange)

Classes: .important, .attention
Icons: 🔔
Use for: Important updates, attention-required items, priority notices

🔔 Important Update

Breaking changes coming next week. Review the migration guide.

🔔 Attention Required

Your subscription expires in 3 days. Please update payment info.

Critical & Errors (Red)

Classes: .danger, .critical, .error
Icons: 🚨 / ❌
Use for: Critical errors, security alerts, dangerous operations

🚨 Critical Error

Database connection failed. Contact support immediately.

🚨 Security Alert

Suspicious activity detected. Change your password now.

❌ Processing Error

Request failed. Check input data and try again. Error: AUTH_001

Examples & Demos (Cyan)

Classes: .example, .demo
Icons: 🔍
Use for: Code examples, interactive demos, tutorials

🔍 Live Example

Try the interactive demo below to see this feature in action.

🔍 Code Demo

This example shows proper implementation of the authentication flow.

Quotes & Citations (Purple)

Classes: .quote, .citation
Icons: 💬
Use for: User testimonials, research citations, external quotes

💬 Customer Testimonial

"This platform transformed our workflow completely!" - Jane Smith, CTO

💬 Research Finding

Studies show 87% productivity improvement with integrated tools (DevSurvey 2024).

Resources & Downloads (Teal)

Classes: .download, .resource
Icons: 📁
Use for: Available downloads, additional resources, external links

📁 Download Available

Get the complete source code for this example. Compatible with Rails 8.0+.

📁 Additional Resources

Check our tutorial library and community examples for advanced implementations.

Dark Mode Support

All blockquote styles automatically adapt to dark mode with appropriate color variations:

• Light mode: Uses bright backgrounds with subtle gradients
• Dark mode: Uses darker backgrounds with translucent colored overlays
• Icons and borders: Maintain visibility and contrast in both themes

Implementation Examples

Multiple Blockquotes in Sequence

ℹ️ Getting Started

First, ensure you have the required dependencies installed.

⚠️ Before You Begin

Make sure to backup your current configuration.

✅ Ready to Go

Once setup is complete, you're ready to start building!

Mixed Content Blockquotes

🔍 Advanced Example

Here's how to implement custom validation:

validates :email, presence: true, uniqueness: true
validates :password, length: { minimum: 8 }

Remember to handle edge cases appropriately.

Nested Information

💡 Pro Tip

For complex operations, consider using service objects:

1. Keep controllers thin
2. Encapsulate business logic
3. Make code testable

This approach improves maintainability significantly.

CSS Customization

To modify or extend the blockquote styles, edit app/assets/stylesheets/markdown.css. Each blockquote type follows this pattern:

.markdown-content blockquote.your-class {
  border-left-color: #your-color;
  background: linear-gradient(135deg, #light-color 0%, #darker-color 100%);
}

.markdown-content blockquote.your-class:after {
  content: "your-emoji";
}

For dark mode variations, add corresponding styles:

.dark .markdown-content blockquote.your-class {
  background: linear-gradient(135deg, rgba(r, g, b, 0.15) 0%, rgba(r, g, b, 0.05) 100%);
  border-left-color: #bright-variant;
}

Default Blockquote

This is a default blockquote that demonstrates the enhanced styling inspired by ReadMe's documentation. It features beautiful gradients, subtle shadows, and improved typography that makes important information stand out.

Links and Media

Basic Links

Internal link to headings External link to Rails Link with title

Reference-style Links

This is a paragraph with reference link and another reference link.

Automatic Links

Visit https://example.com or email support@example.com for more information.

Image Examples

Linked Images

Advanced Elements

Horizontal Rules

You can create horizontal rules using three or more hyphens:

Or three or more asterisks:

Or three or more underscores:

Definition Lists

Term 1

Definition for term 1

Term 2

Definition for term 2

Another definition for term 2

API Endpoint

A specific URL where an API can access the resources it needs

REST

Representational State Transfer - an architectural style for web services

Abbreviations

The HTML specification is maintained by the W3C.

Footnotes

This is a paragraph with a footnote¹ and another footnote².

Math Expressions (if supported)

Inline math: \(E = mc^2\)

Block math:

HTML Elements

You can use highlighted text and keyboard inputs.

Mixed Content Examples

API Documentation Example

📡 API Endpoint

POST /api/v1/documents

Creates a new document in the specified organization.

Request Headers:

Content-Type: application/json
Authorization: Bearer your-api-token
X-Organization-ID: org_123456789

Request Body:

{
  "title": "My New Document",
  "content": "# Hello World\n\nThis is my first document.",
  "tags": ["tutorial", "getting-started"],
  "metadata": {
    "author": "John Doe",
    "version": "1.0"
  }
}

Response:

The API returns different status codes depending on the outcome:

Tutorial Section Example

Step 1: Installation

💡 Prerequisites

Before starting, ensure you have Ruby 3.4+ and Rails 8.0+ installed on your system.

Install the required gems:

bundle add kramdown rouge

Step 2: Configuration

Create the configuration file:

# config/initializers/kramdown.rb
Kramdown.configure do |config|
  config.syntax_highlighter = 'rouge'
  config.enable_coderay = false
  config.math_engine = 'mathjax'
end

Step 3: Implementation

• Add Kramdown to Gemfile
• Configure syntax highlighting
• Test with sample content
• Deploy to production

✅ Success!

You have successfully configured Kramdown for your Rails application. Your documentation will now render with beautiful styling and syntax highlighting.

Summary

This comprehensive test file demonstrates:

• Complete heading hierarchy (H1-H6)
• Rich text formatting (bold, italic, strikethrough, code)
• Advanced list structures (nested, mixed, task lists)
• Complex tables with various content types
• Extensive code examples in multiple languages
• Comprehensive blockquote system with 8 different types and styling classes
• Various link types and media embedding
• Advanced markdown features (footnotes, definitions, math)
• Mixed content examples showing real-world usage

The enhanced styling includes:

• Inline Code: Proper line wrapping with word-break: break-word
• Blockquotes: ReadMe-inspired design with gradients, icons, and color coding
• Code Blocks: Modern gradient backgrounds with syntax highlighting
• Tables: Clean, responsive design with proper spacing
• Links: Hover effects and consistent styling
• Responsive Design: Mobile-optimized layouts
• Dark Mode: Full dark theme support across all elements

🎉 Final Note

This documentation system provides a professional, modern appearance that enhances readability and user experience. Every element has been carefully styled to create a cohesive and beautiful documentation platform, with special attention to the comprehensive blockquote system that helps organize information visually.