opaque_id 1.4.0 → 1.6.0

data/lib/opaque_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpaqueId
-  VERSION = '1.4.0'
+  VERSION = '1.6.0'
 end

data/lib/opaque_id.rb

@@ -9,6 +9,9 @@ module OpaqueId
   class GenerationError < Error; end
   class ConfigurationError < Error; end
 
+  # Slug-like alphabet for URL-safe, double-click selectable IDs (36 characters)
+  SLUG_LIKE_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+
   # Standard URL-safe alphabet (64 characters)
   STANDARD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
 
@@ -17,7 +20,7 @@ module OpaqueId
 
   class << self
     # Generate a cryptographically secure random ID
-    def generate(size: 21, alphabet: ALPHANUMERIC_ALPHABET)
+    def generate(size: 18, alphabet: SLUG_LIKE_ALPHABET)
       raise ConfigurationError, 'Size must be positive' unless size.positive?
       raise ConfigurationError, 'Alphabet cannot be empty' if alphabet.nil? || alphabet.empty?
 

data/release-please-config.json

@@ -3,7 +3,8 @@
   "packages": {
     ".": {
       "package-name": "opaque_id",
-      "version-file": "lib/opaque_id/version.rb"
+      "version-file": "lib/opaque_id/version.rb",
+      "tag-template": "v${version}"
     }
   },
   "changelog-sections": [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opaque_id
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Joe Nyaggah
@@ -156,14 +156,6 @@ files:
 - lib/opaque_id/model.rb
 - lib/opaque_id/version.rb
 - release-please-config.json
-- tasks/0001-prd-opaque-id-gem.md
-- tasks/0002-prd-publishing-release-automation.md
-- tasks/0003-prd-documentation-site.md
-- tasks/references/opaque_gem_requirements.md
-- tasks/references/original_identifiable_concern_and_nanoid.md
-- tasks/tasks-0001-prd-opaque-id-gem.md
-- tasks/tasks-0002-prd-publishing-release-automation.md
-- tasks/tasks-0003-prd-documentation-site.md
 homepage: https://github.com/nyaggah/opaque_id
 licenses:
 - MIT

data/tasks/0001-prd-opaque-id-gem.md

@@ -1,202 +0,0 @@
-# Product Requirements Document: OpaqueId Ruby Gem
-
-## Introduction/Overview
-
-The OpaqueId gem is a Ruby library that generates cryptographically secure, collision-free opaque identifiers for ActiveRecord models. This gem replaces the existing `nanoid.rb` dependency by implementing the same functionality using Ruby's built-in `SecureRandom` methods, eliminating external dependencies while maintaining the same security and performance characteristics.
-
-The primary problem this gem solves is preventing the exposure of incremental database IDs in public URLs and APIs, which can reveal business metrics, enable enumeration attacks, and expose internal system architecture. Instead, it provides opaque, non-sequential identifiers that are URL-friendly and cryptographically secure.
-
-## Goals
-
-1. **Replace nanoid.rb dependency** - Implement equivalent functionality using Ruby's built-in SecureRandom
-2. **Maintain security standards** - Provide cryptographically secure ID generation with unbiased distribution
-3. **Ensure performance** - Achieve 1M+ IDs/sec for 64-character alphabets, 180K+ IDs/sec for 36-character alphabets
-4. **Simplify integration** - Provide seamless ActiveRecord integration with minimal configuration
-5. **Enable wide adoption** - Create comprehensive documentation accessible to all Rails developers
-6. **Ensure reliability** - Implement robust collision detection and retry logic
-7. **Maintain compatibility** - Support Rails 8.0+ and Ruby 3.2+ environments
-
-## User Stories
-
-### Primary Users: Rails Developers
-
-**As a Rails developer**, I want to generate opaque IDs for my models so that I can expose public identifiers without revealing database structure.
-
-**As a Rails developer**, I want to easily integrate opaque ID generation into my existing models so that I don't have to manually implement ID generation logic.
-
-**As a Rails developer**, I want to configure ID generation parameters (length, alphabet, column name) so that I can customize the behavior for different use cases.
-
-**As a Rails developer**, I want to find records by their opaque ID so that I can build public-facing APIs and URLs.
-
-**As a Rails developer**, I want the gem to handle collision detection automatically so that I don't have to worry about duplicate IDs.
-
-**As a Rails developer**, I want comprehensive documentation and examples so that I can quickly understand and implement the gem in my project.
-
-### Secondary Users: Security-Conscious Teams
-
-**As a security-conscious developer**, I want cryptographically secure ID generation so that my public identifiers cannot be predicted or enumerated.
-
-**As a security-conscious developer**, I want unbiased character distribution so that my IDs have maximum entropy and cannot be analyzed for patterns.
-
-## Functional Requirements
-
-### Core ID Generation
-
-1. The system must generate cryptographically secure random IDs using Ruby's `SecureRandom`
-2. The system must implement rejection sampling algorithm to ensure unbiased character distribution
-3. The system must provide optimized fast path for 64-character alphabets using bitwise operations
-4. The system must support custom alphabet configurations
-5. The system must support custom ID length configurations
-6. The system must provide two predefined alphabets: ALPHANUMERIC_ALPHABET (36 chars) and STANDARD_ALPHABET (64 chars)
-
-### ActiveRecord Integration
-
-7. The system must provide `OpaqueId::Model` concern for easy ActiveRecord integration
-8. The system must automatically generate opaque IDs on model creation via `before_create` callback
-9. The system must provide `find_by_opaque_id` and `find_by_opaque_id!` class methods
-10. The system must support custom column names via `opaque_id_column` configuration
-11. The system must implement collision detection with configurable retry attempts
-12. The system must raise appropriate errors when collision resolution fails
-
-### Rails Generator (Optional Convenience Tool)
-
-13. The system must provide optional Rails generator `opaque_id:install` for creating migrations and updating models
-14. The system must generate migration files that add opaque_id column with unique index
-15. The system must automatically add `include OpaqueId::Model` to the corresponding model file
-16. The system must support custom column names via generator options
-17. The system must require explicit table name argument and show clear usage instructions when run without arguments
-18. The system must work with any existing table (new or existing models)
-19. The system must handle edge cases gracefully (missing model file, already included, different class names)
-
-### Configuration Options
-
-20. The system must support `opaque_id_column` configuration (default: `:opaque_id`)
-21. The system must support `opaque_id_length` configuration (default: `18`)
-22. The system must support `opaque_id_alphabet` configuration (default: `ALPHANUMERIC_ALPHABET`)
-23. The system must support `opaque_id_require_letter_start` configuration (default: `true`)
-24. The system must support `opaque_id_purge_chars` configuration (default: `nil`)
-25. The system must support `opaque_id_max_retry` configuration (default: `1000`)
-
-### Error Handling
-
-26. The system must raise `OpaqueId::ConfigurationError` for invalid size or empty alphabet
-27. The system must raise `OpaqueId::GenerationError` when collision resolution fails
-28. The system must provide clear error messages for debugging
-
-### Standalone Usage
-
-29. The system must provide `OpaqueId.generate` method for standalone ID generation
-30. The system must support all configuration options in standalone generation
-31. The system must maintain the same security and performance characteristics in standalone mode
-
-## Non-Goals (Out of Scope)
-
-1. **Other ORM Support** - Will not support Mongoid, Sequel, or other ORMs in initial release
-2. **Non-Rails Usage** - Will not provide standalone Ruby usage without ActiveRecord dependency
-3. **Custom Algorithms** - Will not implement alternative ID generation algorithms beyond rejection sampling
-4. **Database Migrations** - Will not provide automatic database migration for existing records
-5. **ID Validation** - Will not provide built-in ID format validation (users can implement their own)
-6. **Bulk Generation** - Will not provide optimized bulk ID generation methods
-7. **ID Prefixes/Suffixes** - Will not support adding prefixes or suffixes to generated IDs
-8. **Custom Random Sources** - Will not support custom random number generators beyond SecureRandom
-9. **Interactive Generator Mode** - Will not provide interactive prompts for generator arguments
-10. **Backward Compatibility** - Will not maintain compatibility with existing `public_id` implementations
-
-## Design Considerations
-
-### API Design
-
-- Follow Rails conventions for ActiveRecord concerns and generators
-- Use descriptive method names that clearly indicate functionality
-- Provide both safe (`find_by_opaque_id`) and unsafe (`find_by_opaque_id!`) lookup methods
-- Use class-level configuration options for easy customization
-- Follow Devise-style generator pattern for seamless integration
-
-### Performance Optimization
-
-- Implement fast path for 64-character alphabets using bitwise operations (`byte & 63`)
-- Use rejection sampling with optimal mask calculation for unbiased distribution
-- Pre-allocate string capacity to avoid memory reallocation during generation
-- Batch random byte generation to minimize SecureRandom calls
-
-### Security Considerations
-
-- Use only cryptographically secure random number generation
-- Implement proper rejection sampling to avoid modulo bias
-- Provide sufficient entropy through configurable alphabet sizes
-- Ensure IDs cannot be predicted or enumerated
-
-## Technical Considerations
-
-### Dependencies
-
-- **ActiveRecord**: >= 6.0 (targeting Rails 8.0+ compatibility)
-- **ActiveSupport**: >= 6.0 (for concern functionality)
-- **Ruby**: >= 3.2 (for modern Ruby features and performance)
-
-### Testing Framework
-
-- Use **Minitest** instead of RSpec for consistency with Rails conventions
-- Implement comprehensive unit tests for all public methods
-- Include statistical tests for character distribution uniformity
-- Add performance benchmarks to ensure performance requirements are met
-- Test edge cases including collision scenarios and error conditions
-
-### File Structure
-
-```
-lib/
-├── opaque_id.rb                 # Main module with generator
-├── opaque_id/
-│   ├── version.rb               # Version constant
-│   └── model.rb                 # ActiveRecord concern
-└── generators/
-    └── opaque_id/
-        ├── install_generator.rb  # Migration generator
-        └── templates/
-            └── migration.rb.tt   # Migration template
-```
-
-### Error Classes
-
-- `OpaqueId::Error` - Base error class
-- `OpaqueId::GenerationError` - ID generation failures
-- `OpaqueId::ConfigurationError` - Invalid configuration
-
-## Success Metrics
-
-### Performance Metrics
-
-- **Standard alphabet (64 chars)**: Achieve ~1.2M IDs/sec generation rate
-- **Alphanumeric alphabet (36 chars)**: Achieve ~180K IDs/sec generation rate
-- **Custom alphabet (20 chars)**: Achieve ~150K IDs/sec generation rate
-
-### Quality Metrics
-
-- **Test Coverage**: Achieve 95%+ code coverage
-- **Documentation**: Provide comprehensive README with examples
-- **Error Handling**: All error conditions properly tested and documented
-
-### Adoption Metrics
-
-- **Gem Downloads**: Target 1000+ downloads in first month
-- **GitHub Stars**: Target 50+ stars within 6 months
-- **Community Feedback**: Positive reception from Rails community
-
-## Open Questions
-
-1. **Version Strategy**: Should we follow semantic versioning strictly, or use a different versioning strategy for a utility gem?
-
-2. **Backward Compatibility**: How should we handle potential breaking changes in future versions, especially regarding default configurations?
-
-3. **Performance Testing**: Should we include automated performance regression testing in CI/CD, or rely on manual benchmarking?
-
-4. **Documentation Hosting**: Should we create a dedicated documentation site, or rely on GitHub README and inline documentation?
-
-5. **Community Contributions**: What level of community contribution should we expect, and how should we structure the project to encourage contributions?
-
-6. **Integration Testing**: Should we test against multiple Rails versions in CI, or focus on the target Rails 8.0+ range?
-
-7. **Security Auditing**: Should we implement any security auditing tools or processes for the random number generation?
-
-8. **Migration Path**: How should we help users migrate from nanoid.rb to opaque_id, if at all?

data/tasks/0002-prd-publishing-release-automation.md

@@ -1,206 +0,0 @@
-# Product Requirements Document: Publishing & Release Automation
-
-## Introduction/Overview
-
-This PRD outlines the implementation of a fully automated publishing and release system for the OpaqueId Ruby gem. The system will automatically version, test, and publish releases to RubyGems.org based on conventional commits, eliminating manual release processes and ensuring consistent, professional releases.
-
-**Problem**: Manual release processes are error-prone, time-consuming, and inconsistent. Without automated versioning and publishing, releases can be delayed, version numbers can be inconsistent, and changelogs can be incomplete.
-
-**Goal**: Implement a fully automated CI/CD pipeline that handles versioning, testing, changelog generation, and publishing based on conventional commits and the state of the main branch.
-
-## Goals
-
-1. **Automated Versioning**: Automatically determine version bumps (patch/minor/major) based on conventional commit types
-2. **Automated Publishing**: Automatically publish to RubyGems.org when changes are ready
-3. **Quality Gates**: Ensure all tests pass, code quality standards are met, and security checks pass before release
-4. **Automated Changelog**: Generate changelog entries from conventional commits
-5. **Dependency Management**: Automatically check for and update dependencies weekly
-6. **Commit Standardization**: Enforce conventional commit format for consistent messaging
-7. **Security**: Use RubyGems trusted publishing for secure, keyless releases
-
-## User Stories
-
-### As a Developer
-
-- **US1**: I want my commits to automatically trigger appropriate version bumps so that I don't have to manually manage version numbers
-- **US2**: I want releases to be published automatically when I push to main so that I don't have to remember to manually publish
-- **US3**: I want commit message validation so that I follow consistent formatting standards
-- **US4**: I want automated dependency updates so that my gem stays secure and up-to-date
-
-### As a Maintainer
-
-- **US5**: I want automated testing and quality checks before release so that I can trust the published code
-- **US6**: I want automated changelog generation so that users know what changed in each release
-- **US7**: I want security scanning before release so that vulnerabilities are caught early
-
-### As a User
-
-- **US8**: I want consistent, predictable releases so that I can trust the gem's stability
-- **US9**: I want clear changelogs so that I understand what changed between versions
-
-## Functional Requirements
-
-### 1. Conventional Commits Integration
-
-1.1. **Commit Message Validation**: Enforce conventional commit format (feat:, fix:, docs:, etc.) on all commits
-1.2. **Commit Linting**: Use commitlint or similar tool to validate commit message format
-1.3. **Pre-commit Hooks**: Automatically validate commit messages before they are accepted
-1.4. **Commit Types**: Support standard types: feat, fix, docs, style, refactor, perf, test, chore, ci, build
-
-### 2. Automated Versioning
-
-2.1. **Semantic Versioning**: Use semantic versioning (MAJOR.MINOR.PATCH) based on conventional commits
-2.2. **Version Bump Logic**:
-
-- `feat:` commits → MINOR version bump
-- `fix:` commits → PATCH version bump
-- `BREAKING CHANGE:` or `!` → MAJOR version bump
-- Other types → no version bump
-  2.3. **Version Detection**: Automatically detect when version should be bumped based on unreleased commits
-  2.4. **Version File Update**: Automatically update `lib/opaque_id/version.rb` with new version
-
-### 3. GitHub Actions Workflow
-
-3.1. **Single Workflow**: Update existing `main.yml` to include release automation
-3.2. **Trigger Conditions**: Run on push to main branch when unreleased changes exist
-3.3. **Workflow Steps**:
-
-- Checkout code
-- Setup Ruby environment
-- Install dependencies
-- Run tests
-- Run RuboCop
-- Security audit
-- Determine version bump
-- Update version file
-- Generate changelog
-- Create git tag
-- Publish to RubyGems.org
-- Create GitHub release
-
-### 4. Quality Gates
-
-4.1. **Test Execution**: Run full test suite before any release
-4.2. **Code Quality**: Run RuboCop and fail if violations exist
-4.3. **Security Scanning**: Run `bundle audit` to check for vulnerable dependencies
-4.4. **Dependency Check**: Ensure all dependencies are up-to-date and secure
-
-### 5. Changelog Generation
-
-5.1. **Automated Generation**: Generate changelog from conventional commits since last release
-5.2. **Changelog Format**: Use conventional changelog format with categorized sections
-5.3. **Changelog Sections**: Features, Bug Fixes, Breaking Changes, Documentation, etc.
-5.4. **Changelog Update**: Automatically update `CHANGELOG.md` with new entries
-
-### 6. RubyGems Publishing
-
-6.1. **Trusted Publishing**: Use RubyGems trusted publishing (no API keys required)
-6.2. **MFA Enforcement**: Ensure MFA is required for publishing (already configured)
-6.3. **Build Process**: Build gem package before publishing
-6.4. **Publish Process**: Automatically push to RubyGems.org when all checks pass
-
-### 7. Dependabot Integration
-
-7.1. **Weekly Updates**: Check for dependency updates every Monday at 9 AM
-7.2. **Update Types**: Check for both direct and indirect dependency updates
-7.3. **Security Updates**: Prioritize security-related updates
-7.4. **Update Strategy**: Create pull requests for dependency updates
-
-### 8. Git Tag Management
-
-8.1. **Automatic Tagging**: Create git tags for each release (e.g., `v1.2.3`)
-8.2. **Tag Format**: Use semantic versioning format with `v` prefix
-8.3. **Tag Push**: Automatically push tags to GitHub repository
-8.4. **GitHub Release**: Create GitHub release with changelog and tag
-
-## Non-Goals (Out of Scope)
-
-1. **Manual Release Override**: No manual release triggers or overrides
-2. **Multiple Branch Support**: Only support releases from main branch
-3. **Pre-release Versions**: No support for alpha/beta/rc versions initially
-4. **Monorepo Support**: Single gem repository only
-5. **Custom Versioning Logic**: No custom versioning rules beyond conventional commits
-6. **Rollback Automation**: No automatic rollback of failed releases
-
-## Technical Considerations
-
-### Dependencies
-
-- **Release Please**: Google's tool for PR-based versioning and changelog generation
-- **Bundler's release tasks**: Built-in rake tasks for building and tagging (already present)
-- **commitlint**: For commit message validation (optional)
-- **bundle-audit**: For security scanning
-
-### GitHub Actions
-
-- **googleapis/release-please-action**: For creating release PRs and versioning
-- **rubygems/release-gem**: For RubyGems publishing with trusted publishing
-- **actions/checkout**: For code checkout
-- **ruby/setup-ruby**: For Ruby environment setup
-
-### Configuration Files
-
-- **release-please-config.json**: Release Please configuration
-- **dependabot.yml**: Dependency update configuration
-- **.github/workflows/release-please.yml**: Release PR workflow
-- **.github/workflows/publish.yml**: Publishing workflow
-
-### RubyGems Trusted Publishing
-
-- Configure trusted publishing on RubyGems.org
-- Use GitHub OIDC for authentication
-- No API keys or secrets required
-
-## Success Metrics
-
-1. **Release Automation**: 100% of releases are automated (no manual intervention)
-2. **Release Frequency**: Ability to release multiple times per day if needed
-3. **Quality Gates**: 0% of releases with failing tests or security issues
-4. **Commit Compliance**: 100% of commits follow conventional commit format
-5. **Dependency Currency**: Dependencies updated within 7 days of availability
-6. **Release Time**: From commit to published gem in under 10 minutes
-
-## Open Questions
-
-1. **Commit Message Enforcement**: Should we use pre-commit hooks or GitHub Actions validation?
-2. **Changelog Format**: Should we use conventional-changelog or custom format?
-3. **Version Bump Strategy**: Should we batch multiple commits into single releases?
-4. **Rollback Strategy**: How should we handle failed releases or rollbacks?
-5. **Notification Strategy**: Should we notify maintainers of successful/failed releases?
-6. **Branch Protection**: Should we require status checks before merging to main?
-
-## Implementation Priority
-
-### Phase 1: Core Automation
-
-- Conventional commits validation
-- Automated versioning
-- Basic GitHub Actions workflow
-- RubyGems publishing
-
-### Phase 2: Quality & Security
-
-- Quality gates (tests, RuboCop, security)
-- Automated changelog generation
-- Dependabot integration
-
-### Phase 3: Polish & Monitoring
-
-- Enhanced notifications
-- Release monitoring
-- Performance optimization
-
-## Acceptance Criteria
-
-- [ ] All commits follow conventional commit format
-- [ ] Version numbers are automatically bumped based on commit types
-- [ ] Releases are automatically published to RubyGems.org
-- [ ] Changelog is automatically generated from commits
-- [ ] All tests pass before release
-- [ ] RuboCop passes before release
-- [ ] Security audit passes before release
-- [ ] Dependencies are automatically updated weekly
-- [ ] Git tags are automatically created for releases
-- [ ] GitHub releases are automatically created
-- [ ] RubyGems trusted publishing is configured
-- [ ] No manual intervention required for releases

data/tasks/0003-prd-documentation-site.md

@@ -1,191 +0,0 @@
-# Product Requirements Document: OpaqueId Documentation Site
-
-## Introduction/Overview
-
-Create a professional documentation website for the OpaqueId Ruby gem using [Just the Docs](https://just-the-docs.com) Jekyll theme. The site will provide comprehensive, developer-focused documentation that mirrors the README content but with improved navigation, search capabilities, and a clean, minimal design similar to the Just the Docs site itself.
-
-**Problem Solved:** The current README is comprehensive but long (1600+ lines), making it difficult to navigate and find specific information quickly. A dedicated documentation site will improve developer experience and make the gem more accessible.
-
-**Goal:** Create a professional, searchable documentation site that makes OpaqueId easy to understand and implement for developers.
-
-## Goals
-
-1. **Improve Developer Experience**: Provide easy navigation and search for finding specific documentation
-2. **Professional Presentation**: Create a polished, modern documentation site that reflects the quality of the gem
-3. **Maintain Content Quality**: Preserve all valuable information from the README while improving organization
-4. **Enable Auto-Deployment**: Set up GitHub Actions for automatic deployment on successful pushes
-5. **Ensure Accessibility**: Make documentation accessible and mobile-friendly
-6. **Minimize Maintenance**: Keep the site simple and maintainable
-
-## User Stories
-
-- **As a developer** evaluating OpaqueId, I want to quickly understand what the gem does and how to install it
-- **As a developer** implementing OpaqueId, I want to find specific configuration options and usage examples
-- **As a developer** troubleshooting issues, I want to search for specific error messages or solutions
-- **As a developer** learning advanced features, I want to explore performance benchmarks and security considerations
-- **As a developer** contributing to the project, I want to understand the development setup and guidelines
-
-## Functional Requirements
-
-### 1. Site Structure & Navigation
-
-1.1. Create a `/docs` directory with Jekyll site structure
-1.2. Implement sidebar navigation based on README Table of Contents
-1.3. Use minimal, flat navigation structure (no collapsible sections)
-1.4. Include search functionality using Just the Docs built-in search
-1.5. Add "Getting Started" quick start guide as a separate page
-
-### 2. Content Organization
-
-2.1. Convert README sections into individual documentation pages
-2.2. Create logical page hierarchy: Home → Getting Started → Installation → Usage → Configuration → etc.
-2.3. Maintain all existing content from README
-2.4. Add code syntax highlighting for Ruby examples
-2.5. Include proper cross-references between pages
-
-### 3. Design & Styling
-
-3.1. Use Just the Docs theme with default light/dark mode switching
-3.2. Apply minimal design similar to just-the-docs.com
-3.3. Include OpaqueId branding and gem badges
-3.4. Ensure responsive design for mobile devices
-3.5. Use consistent typography and spacing
-
-### 4. GitHub Pages Integration
-
-4.1. Configure site for `https://nyaggah.github.io/opaque_id`
-4.2. Set up GitHub Actions workflow for automatic deployment
-4.3. Deploy on successful pushes to main branch
-4.4. Include proper Jekyll configuration for GitHub Pages
-
-### 5. Content Pages
-
-5.1. **Home**: Overview, badges, quick introduction
-5.2. **Getting Started**: Step-by-step installation and basic usage
-5.3. **Installation**: Detailed installation instructions and requirements
-5.4. **Usage**: Standalone and ActiveRecord integration examples
-5.5. **Configuration**: All configuration options and examples
-5.6. **Alphabets**: Built-in alphabets and custom alphabet guide
-5.7. **Algorithms**: Technical details about fast path and unbiased algorithms
-5.8. **Performance**: Benchmarks and optimization tips
-5.9. **Security**: Security considerations and best practices
-5.10. **Use Cases**: Real-world examples and applications
-5.11. **Development**: Contributing guidelines and development setup
-5.12. **API Reference**: Complete method documentation
-
-### 6. Technical Implementation
-
-6.1. Use Jekyll with Just the Docs theme
-6.2. Configure `_config.yml` for GitHub Pages
-6.3. Set up proper front matter for all pages
-6.4. Include necessary Jekyll plugins for GitHub Pages
-6.5. Optimize for fast loading and SEO
-
-## Non-Goals (Out of Scope)
-
-- **Live Code Examples**: No interactive demos or live code execution
-- **Version-Specific Documentation**: Single version documentation only
-- **Automatic README Sync**: Manual content maintenance
-- **Custom Domain**: Using default GitHub.io domain
-- **Breadcrumb Navigation**: Sidebar navigation only
-- **User Authentication**: Public documentation only
-- **Comments/Feedback System**: Static documentation only
-
-## Design Considerations
-
-### Visual Design
-
-- **Theme**: [Just the Docs](https://just-the-docs.com) Jekyll theme
-- **Color Scheme**: Default light/dark mode switching
-- **Layout**: Clean, minimal design with focus on content
-- **Typography**: Clear, readable fonts with proper hierarchy
-- **Navigation**: Left sidebar with flat structure
-
-### Content Structure
-
-- **Homepage**: Hero section with badges, overview, and quick start
-- **Sidebar**: Logical grouping of documentation sections
-- **Search**: Full-text search across all documentation
-- **Code Examples**: Syntax-highlighted Ruby code blocks
-- **Cross-References**: Links between related sections
-
-## Technical Considerations
-
-### Jekyll Configuration
-
-- Use gem-based approach with `just-the-docs` gem
-- Configure for GitHub Pages compatibility
-- Include necessary plugins: jekyll-feed, jekyll-sitemap, jekyll-seo-tag
-- Set up proper permalinks and URL structure
-
-### GitHub Actions Workflow
-
-- Trigger on pushes to main branch
-- Build Jekyll site
-- Deploy to GitHub Pages
-- Include proper error handling and notifications
-
-### File Structure
-
-```
-/docs/
-├── _config.yml
-├── Gemfile
-├── index.md (Home)
-├── getting-started.md
-├── installation.md
-├── usage.md
-├── configuration.md
-├── alphabets.md
-├── algorithms.md
-├── performance.md
-├── security.md
-├── use-cases.md
-├── development.md
-├── api-reference.md
-└── assets/
-    └── images/
-```
-
-## Success Metrics
-
-1. **Developer Adoption**: Increased gem downloads and usage
-2. **User Engagement**: Time spent on documentation pages
-3. **Search Usage**: Frequency of search functionality usage
-4. **Page Performance**: Fast loading times (< 3 seconds)
-5. **Mobile Usage**: Successful mobile documentation access
-6. **SEO Performance**: High search engine rankings for OpaqueId-related queries
-
-## Open Questions
-
-1. Should we include a changelog page or link to GitHub releases?
-2. Do we want to include a "Troubleshooting" section for common issues?
-3. Should we add a "Migration Guide" for users switching from nanoid.rb?
-4. Do we want to include performance comparison charts or keep them as tables?
-5. Should we add a "Community" section with links to discussions and support?
-
-## Implementation Priority
-
-### Phase 1: Core Setup
-
-- Set up Jekyll site structure
-- Configure GitHub Pages deployment
-- Create basic page structure
-
-### Phase 2: Content Migration
-
-- Convert README content to individual pages
-- Set up navigation and cross-references
-- Add code syntax highlighting
-
-### Phase 3: Enhancement
-
-- Add search functionality
-- Optimize performance and SEO
-- Polish design and user experience
-
-### Phase 4: Launch
-
-- Deploy to GitHub Pages
-- Test all functionality
-- Announce to community