opaque_id 1.3.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b3fe09fbe6c8dd3f161f8067f1f4159b20d66987d4f83a1649bfebfe2d68af1
-  data.tar.gz: 3887547bac4c747e9c95b3ff1bbe456ea001d4e0a2432a2186d7a1343f3a40aa
+  metadata.gz: 016b3d2bbd7ae3af1ba38973c0b590164d7be1a4bd60a8c0e0379cfca1c9dc0f
+  data.tar.gz: 2924779f8769585995732ce79da51b8a1171c0b22fd33636c6476f77815adb44
 SHA512:
-  metadata.gz: d3a0326565ef4d064bc651805c9126d313d22cfffbc26fb10ce5f38a9be794a3d67611838465d74eb59e27313bf8a2db1f1669055b79410e9c4c1cbfd6697a1b
-  data.tar.gz: afe1a2e68f187435cd3efe01871f926b191335bf3bf19958afe66c6e8e873321809e17eb699ff3f6d58cb6175d3296288abdaaa5d8c2b9ccc0ab87cff8c99fe9
+  metadata.gz: 82206f53378e08c302fbb9bd56caf94238e3b0780b6a271732d00d04f0e7e37136c1c6c941ef58fe6c6fffd154c7ce1b82c0b12b76240d23399007d34d81a0bd
+  data.tar.gz: b5d588f50a7a2337b42fc4e021b9aef658cf3e9f92c64fe5c21c7bf901560d5575b48c05fe72edefa77112175357562b0497c4c3d2ba73dd23be2165b6eadd87

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.3.0"
+  ".": "1.6.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,142 @@ All notable changes to the OpaqueId gem will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0](https://github.com/nyaggah/opaque_id/compare/opaque_id-v1.5.0...opaque_id/v1.6.0) (2025-10-03)
+
+
+### Features
+
+* add external links to sidebar using JavaScript ([cd77079](https://github.com/nyaggah/opaque_id/commit/cd770795936ca76633a18f80cba8482ec09db8e2))
+* add SLUG_LIKE_ALPHABET as default for URL-safe IDs ([1e52b17](https://github.com/nyaggah/opaque_id/commit/1e52b174d70ca72b74badf399401605b307e3604))
+* add Table of Contents to all documentation pages ([9472175](https://github.com/nyaggah/opaque_id/commit/94721752270211d5b7db460da61d79a8a81218b2))
+* complete Table of Contents implementation ([5b037e4](https://github.com/nyaggah/opaque_id/commit/5b037e42692803204bc4d8991b6d2e0c9639a05c))
+* implement dynamic copyright year ([b86cea6](https://github.com/nyaggah/opaque_id/commit/b86cea66e60939377c6b0a67c1d385c9bf4bece3))
+* improve documentation site theme and navigation ([304f845](https://github.com/nyaggah/opaque_id/commit/304f845a47397ea2a15f12d2c635144b39be431b))
+* improve generator API and add custom column configuration ([5c1a570](https://github.com/nyaggah/opaque_id/commit/5c1a5703dee269f6985d26096942c086787296f3))
+* initial release of OpaqueId gem v0.1.0 ([3a90274](https://github.com/nyaggah/opaque_id/commit/3a9027403552f8160e3aaf413d1e99ce8c63bbe4))
+
+
+### Bug Fixes
+
+* add frozen string literal comment to docs/Gemfile ([2d653a7](https://github.com/nyaggah/opaque_id/commit/2d653a7bbc071e67e94e63ebc1602768b8d04456))
+* add Release Please manifest and update workflow configuration ([f33ce6c](https://github.com/nyaggah/opaque_id/commit/f33ce6c96805b6c670cd1eedf5ebed2a46e8ffa6))
+* add required permissions for Release Please job ([cdf8d2b](https://github.com/nyaggah/opaque_id/commit/cdf8d2bfc5dbea9a9ec40411a988191ba91913fa))
+* configure just-the-docs theme for GitHub Pages compatibility ([c2fb96c](https://github.com/nyaggah/opaque_id/commit/c2fb96c46e99fd5287520e01c3bc2dd7bd5d4817))
+* correct aux_links configuration format ([61b3fb9](https://github.com/nyaggah/opaque_id/commit/61b3fb9441ce3cfc3cf30637c277d19135f89dab))
+* correct release-please tag format ([b4c31e5](https://github.com/nyaggah/opaque_id/commit/b4c31e5d0f4878878dd728e82fe9f5eb09ce5b82))
+* improve publish workflow trigger reliability ([9c6e240](https://github.com/nyaggah/opaque_id/commit/9c6e2402474d8ecf8a3f754a9f2ca149a63bf1d1))
+* improve statistical test reliability for CI ([c9b0d52](https://github.com/nyaggah/opaque_id/commit/c9b0d52fb4e9559aad489fcf58bdff1917d613a6))
+* remove unsupported Release Please configuration parameters ([e3b0d2a](https://github.com/nyaggah/opaque_id/commit/e3b0d2ac96b905316a78992004fae83423991632))
+* resolve CSS linting warnings ([d01e8c0](https://github.com/nyaggah/opaque_id/commit/d01e8c05628b7f2bd8b39a13325112168cf4e689))
+* resolve dependency version conflicts and improve test robustness ([af43e13](https://github.com/nyaggah/opaque_id/commit/af43e13393a452f11ce32bafb26a267d1460736c))
+* resolve TOC rendering and improve workflow configuration ([244d532](https://github.com/nyaggah/opaque_id/commit/244d5321e5b18091d8599bd772a28f5a30239c80))
+* update deprecated platform specifications in docs/Gemfile ([cf96134](https://github.com/nyaggah/opaque_id/commit/cf9613499150dd7152bff38aa8f8fe7ab9923eb5))
+* use correct aux_links format ([d4a4bc0](https://github.com/nyaggah/opaque_id/commit/d4a4bc0c11bc66b661034915b471ed762611d821))
+
+
+### Documentation
+
+* final cleanup of over-inflated claims ([795b5b0](https://github.com/nyaggah/opaque_id/commit/795b5b0071a098f718a40e84e81ceba4525b8d3b))
+* implement comprehensive documentation site with dark theme ([19cc9e3](https://github.com/nyaggah/opaque_id/commit/19cc9e30c584658559c5404a4518e871039cc223))
+* implement comprehensive documentation site with dark theme ([a249c6a](https://github.com/nyaggah/opaque_id/commit/a249c6ad2253439f0d070620a914ff87597cf7cb))
+* tone down over-inflated claims and remove unsubstantiated benchmarks ([6536b87](https://github.com/nyaggah/opaque_id/commit/6536b87f9a9c2049497328319641ff21368c6032))
+* tone down pretentious language in algorithms intro ([58c0caf](https://github.com/nyaggah/opaque_id/commit/58c0caf116228401b6218ec589a35b350d068b49))
+
+
+### Styles
+
+* improve code formatting in generator ([ce52021](https://github.com/nyaggah/opaque_id/commit/ce52021cd60e3594dc1ee34e5b96d48568008b5a))
+
+
+### Miscellaneous Chores
+
+* configure just-the-docs theme ([3dfcac8](https://github.com/nyaggah/opaque_id/commit/3dfcac88099e65e61931e558e9242050bdbf0bc9))
+* **main:** release 1.0.0 ([43282c5](https://github.com/nyaggah/opaque_id/commit/43282c5865aae3f136c9eaa49f013066a2359826))
+* **main:** release 1.0.0 ([b8271ad](https://github.com/nyaggah/opaque_id/commit/b8271ad43cf6fab4687276258f0105c06a87bff7))
+* **main:** release 1.0.1 ([4ee2e2c](https://github.com/nyaggah/opaque_id/commit/4ee2e2c69905e71d6c5048617af09b65cbb9e12a))
+* **main:** release 1.0.1 ([e6cd2f8](https://github.com/nyaggah/opaque_id/commit/e6cd2f8f8ff545ad3010598488f71956e36a88c5))
+* **main:** release 1.0.2 ([d5c7423](https://github.com/nyaggah/opaque_id/commit/d5c7423cf06ae7638d95cdd29b2631049efed727))
+* **main:** release 1.0.2 ([365dff8](https://github.com/nyaggah/opaque_id/commit/365dff87a044aa967906866d6ace8d1ccad08c78))
+* **main:** release opaque_id 1.1.0 ([df65c79](https://github.com/nyaggah/opaque_id/commit/df65c79d0efaee1dcd89b8af2f1b1c712c3cc2cd))
+* **main:** release opaque_id 1.1.0 ([e2a4ee0](https://github.com/nyaggah/opaque_id/commit/e2a4ee0fd2d31132bc5bc0de6b6115f3ceae8afb))
+* **main:** release opaque_id 1.2.0 ([1987b07](https://github.com/nyaggah/opaque_id/commit/1987b07b3db92216f3fbbe807c3ad66ca105866e))
+* **main:** release opaque_id 1.2.0 ([aacd20a](https://github.com/nyaggah/opaque_id/commit/aacd20aa5eaa1fe2fa76d89cc6bdab26214b744d))
+* **main:** release opaque_id 1.3.0 ([964b1b4](https://github.com/nyaggah/opaque_id/commit/964b1b421b1fac3fe43b15549e0e6b216b600357))
+* **main:** release opaque_id 1.3.0 ([76453ad](https://github.com/nyaggah/opaque_id/commit/76453ad18b2d2b81548e49dafb5dde6fb52abcca))
+* **main:** release opaque_id 1.4.0 ([6c3ccd1](https://github.com/nyaggah/opaque_id/commit/6c3ccd108b3eea0bbf0ac71fda4ccc0e47e97b95))
+* **main:** release opaque_id 1.4.0 ([3d9d818](https://github.com/nyaggah/opaque_id/commit/3d9d818b34771ad1ca729f3f9b443784a6965568))
+* **main:** release opaque_id 1.5.0 ([113af74](https://github.com/nyaggah/opaque_id/commit/113af74dda07330bf7108977147362385dc806ae))
+* **main:** release opaque_id 1.5.0 ([ff14fe9](https://github.com/nyaggah/opaque_id/commit/ff14fe92d94cf4ecbe5aaeb31ad6cd044bfa89d0))
+* remove tasks/ directory from source control ([e007ead](https://github.com/nyaggah/opaque_id/commit/e007ead90fa3fbb62ab17e334563e69899afb259))
+* sync version to 1.0.2 ([2f870c8](https://github.com/nyaggah/opaque_id/commit/2f870c89d486f0a5cda8ef37e5544c29c8fa2919))
+* update author name and GitHub URLs ([e911548](https://github.com/nyaggah/opaque_id/commit/e911548e89e1e60ac3281157059f7c7b812750bd))
+* update bundle and add Linux platform support ([661842f](https://github.com/nyaggah/opaque_id/commit/661842f0ba66ce36962bb11f75a1b0e35eb5a3e7))
+* update Gemfile.lock after dependency check ([058281f](https://github.com/nyaggah/opaque_id/commit/058281f6e07f3c9a1057c6fbeb0200bccf221558))
+
+
+### Code Refactoring
+
+* improve generator code quality and resolve RuboCop issues ([b658bbc](https://github.com/nyaggah/opaque_id/commit/b658bbcb29f6c0134f2bf256b24c5b3c2bccb265))
+* integrate Release Please into main CI workflow ([8a0b189](https://github.com/nyaggah/opaque_id/commit/8a0b189a8bfbfcc07275c9bdda3397ff367b2054))
+* simplify external links implementation ([5cb84c1](https://github.com/nyaggah/opaque_id/commit/5cb84c1e8952a0fd1aa4b9089b9ff11829dc397c))
+
+
+### Tests
+
+* add test for lowercase model names ([8ef4675](https://github.com/nyaggah/opaque_id/commit/8ef4675a0698d2cda054084360c9e80d956ddb14))
+* update tests for SLUG_LIKE_ALPHABET defaults ([d7296c7](https://github.com/nyaggah/opaque_id/commit/d7296c77b1b7a995e7a42b3ba546fdeb8e41c297))
+* update tests for SLUG_LIKE_ALPHABET defaults ([d1f8f26](https://github.com/nyaggah/opaque_id/commit/d1f8f26e7be80f6cbefc98563c0ffa45033372dc))
+
+## [1.5.0](https://github.com/nyaggah/opaque_id/compare/opaque_id/v1.4.0...opaque_id/v1.5.0) (2025-10-03)
+
+
+### Features
+
+* add SLUG_LIKE_ALPHABET as default for URL-safe IDs ([1e52b17](https://github.com/nyaggah/opaque_id/commit/1e52b174d70ca72b74badf399401605b307e3604))
+
+
+### Bug Fixes
+
+* resolve TOC rendering and improve workflow configuration ([244d532](https://github.com/nyaggah/opaque_id/commit/244d5321e5b18091d8599bd772a28f5a30239c80))
+
+
+### Documentation
+
+* final cleanup of over-inflated claims ([795b5b0](https://github.com/nyaggah/opaque_id/commit/795b5b0071a098f718a40e84e81ceba4525b8d3b))
+* tone down over-inflated claims and remove unsubstantiated benchmarks ([6536b87](https://github.com/nyaggah/opaque_id/commit/6536b87f9a9c2049497328319641ff21368c6032))
+* tone down pretentious language in algorithms intro ([58c0caf](https://github.com/nyaggah/opaque_id/commit/58c0caf116228401b6218ec589a35b350d068b49))
+
+
+### Miscellaneous Chores
+
+* remove tasks/ directory from source control ([e007ead](https://github.com/nyaggah/opaque_id/commit/e007ead90fa3fbb62ab17e334563e69899afb259))
+
+
+### Tests
+
+* update tests for SLUG_LIKE_ALPHABET defaults ([d7296c7](https://github.com/nyaggah/opaque_id/commit/d7296c77b1b7a995e7a42b3ba546fdeb8e41c297))
+* update tests for SLUG_LIKE_ALPHABET defaults ([d1f8f26](https://github.com/nyaggah/opaque_id/commit/d1f8f26e7be80f6cbefc98563c0ffa45033372dc))
+
+## [1.4.0](https://github.com/nyaggah/opaque_id/compare/opaque_id/v1.3.0...opaque_id/v1.4.0) (2025-10-02)
+
+
+### Features
+
+* add external links to sidebar using JavaScript ([cd77079](https://github.com/nyaggah/opaque_id/commit/cd770795936ca76633a18f80cba8482ec09db8e2))
+* add Table of Contents to all documentation pages ([9472175](https://github.com/nyaggah/opaque_id/commit/94721752270211d5b7db460da61d79a8a81218b2))
+* complete Table of Contents implementation ([5b037e4](https://github.com/nyaggah/opaque_id/commit/5b037e42692803204bc4d8991b6d2e0c9639a05c))
+
+
+### Bug Fixes
+
+* correct aux_links configuration format ([61b3fb9](https://github.com/nyaggah/opaque_id/commit/61b3fb9441ce3cfc3cf30637c277d19135f89dab))
+* use correct aux_links format ([d4a4bc0](https://github.com/nyaggah/opaque_id/commit/d4a4bc0c11bc66b661034915b471ed762611d821))
+
+
+### Code Refactoring
+
+* simplify external links implementation ([5cb84c1](https://github.com/nyaggah/opaque_id/commit/5cb84c1e8952a0fd1aa4b9089b9ff11829dc397c))
+
 ## [1.3.0](https://github.com/nyaggah/opaque_id/compare/opaque_id/v1.2.0...opaque_id/v1.3.0) (2025-10-02)
 
 

data/README.md

@@ -4,7 +4,7 @@
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
 [![Gem Downloads](https://img.shields.io/gem/dt/opaque_id)](https://rubygems.org/gems/opaque_id)
 
-A Ruby gem for generating cryptographically secure, collision-free opaque IDs for ActiveRecord models. OpaqueId provides a drop-in replacement for `nanoid.rb` using Ruby's built-in `SecureRandom` methods with optimized algorithms for unbiased distribution.
+A simple Ruby gem for generating secure, opaque IDs for ActiveRecord models. OpaqueId provides a drop-in replacement for `nanoid.rb` using Ruby's built-in `SecureRandom` methods, with slug-like IDs as the default for optimal URL safety and user experience.
 
 ## Table of Contents
 
@@ -87,12 +87,12 @@ A Ruby gem for generating cryptographically secure, collision-free opaque IDs fo
 ## Features
 
 - **🔐 Cryptographically Secure**: Uses Ruby's `SecureRandom` for secure ID generation
-- **⚡ High Performance**: Optimized algorithms with fast paths for 64-character alphabets
-- **🎯 Collision-Free**: Built-in collision detection with configurable retry attempts
+- **⚡ Performance Optimized**: Efficient algorithms with fast paths for 64-character alphabets
+- **🎯 Collision Resistant**: Built-in collision detection with configurable retry attempts
 - **🔧 Highly Configurable**: Customizable alphabet, length, column name, and validation rules
-- **🚀 Rails Integration**: Seamless ActiveRecord integration with automatic ID generation
+- **🚀 Rails Integration**: ActiveRecord integration with automatic ID generation
 - **📦 Rails Generator**: One-command setup with `rails generate opaque_id:install`
-- **🧪 Well Tested**: Comprehensive test suite with statistical uniformity tests
+- **🧪 Tested**: Includes test suite with statistical uniformity tests
 - **📚 Rails 8.0+ Compatible**: Built for modern Rails applications
 
 ## Installation
@@ -176,15 +176,34 @@ end
 
 # IDs are automatically generated on creation
 user = User.create!(name: "John Doe")
-puts user.opaque_id  # => "V1StGXR8_Z5jdHi6B-myT"
+puts user.opaque_id  # => "izkpm55j334u8x9y2"
 
 # Find by opaque ID
-user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
-user = User.find_by_opaque_id!("V1StGXR8_Z5jdHi6B-myT")  # raises if not found
+user = User.find_by_opaque_id("izkpm55j334u8x9y2")
+user = User.find_by_opaque_id!("izkpm55j334u8x9y2")  # raises if not found
 ```
 
 ## Usage
 
+### URL-Safe, Double-Click Selectable IDs
+
+OpaqueId defaults to generating **slug-like IDs** that are perfect for URLs and user-facing identifiers:
+
+- **URL-safe**: No special characters that need encoding
+- **Double-click selectable**: Users can easily select the entire ID
+- **Shorter than UUIDs**: 18 characters vs 36 for UUIDs
+- **Collision resistant**: Built on Ruby's `SecureRandom` for security
+
+```ruby
+# Default generation creates slug-like IDs
+id = OpaqueId.generate
+# => "izkpm55j334u8x9y2"  # Perfect for URLs and user selection
+
+# Compare to UUIDs
+uuid = SecureRandom.uuid
+# => "7cb776c5-8c12-4b1a-84aa-9941b815d873"  # Harder to select, longer
+```
+
 ### Standalone ID Generation
 
 OpaqueId can be used independently of ActiveRecord for generating secure IDs in any Ruby application:
@@ -192,13 +211,13 @@ OpaqueId can be used independently of ActiveRecord for generating secure IDs in
 #### Basic Usage
 
 ```ruby
-# Generate with default settings (21 characters, alphanumeric)
+# Generate with default settings (18 characters, slug-like)
 id = OpaqueId.generate
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2"
 
 # Custom length
 id = OpaqueId.generate(size: 10)
-# => "V1StGXR8_Z5"
+# => "izkpm55j334u"
 
 # Custom alphabet
 id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
@@ -210,7 +229,7 @@ id = OpaqueId.generate(size: 8, alphabet: "ABCDEFGH")
 
 # Generate multiple IDs
 ids = 5.times.map { OpaqueId.generate(size: 8) }
-# => ["V1StGXR8", "Z5jdHi6B", "myT12345", "ABCdefGH", "IJKlmnoP"]
+# => ["izkpm55j", "334u8x9y", "2abc1234", "def5678g", "hij9klmn"]
 ```
 
 #### Standalone Use Cases
@@ -229,7 +248,7 @@ class BackgroundJob
 end
 
 job_id = BackgroundJob.enqueue(ProcessDataJob, user_id: 123)
-# => "V1StGXR8_Z5jd"
+# => "izkpm55j334u8x9y2"
 ```
 
 ##### Temporary File Names
@@ -243,7 +262,7 @@ def create_temp_file(content)
 end
 
 filename = create_temp_file("Hello World")
-# => "temp_V1StGXR8.txt"
+# => "temp_izkpm55j334u8x9y2.txt"
 ```
 
 ##### Cache Keys
@@ -264,7 +283,7 @@ user_key = CacheManager.user_cache_key(123)
 # => "user:V1StGX:123"
 
 session_key = CacheManager.session_cache_key
-# => "session:V1StGXR8_Z5jdHi6B"
+# => "session:izkpm55j334u8x9y2"
 ```
 
 ##### Webhook Signatures
@@ -281,7 +300,7 @@ class WebhookService
 end
 
 signature = WebhookService.generate_signature({ user_id: 123 })
-# => "1703123456:V1StGXR8_Z5jdHi6B:1234567890"
+# => "1703123456:izkpm55j334u8x9y2:1234567890"
 ```
 
 ##### Database Migration IDs
@@ -309,7 +328,7 @@ class EmailService
 end
 
 tracking_id = EmailService.tracking_pixel_id
-# => "V1StGXR8Z5jdHi6BmyT12"
+# => "izkpm55j334u8x9y2abc"
 
 # Use in email template
 # <img src="https://example.com/track/#{tracking_id}" width="1" height="1" />
@@ -328,7 +347,7 @@ class ApiLogger
 end
 
 request_id = ApiLogger.log_request("/api/users", { page: 1 })
-# => "V1StGXR8_Z5jd"
+# => "izkpm55j334u8x9y2"
 ```
 
 ##### Batch Processing IDs
@@ -350,9 +369,9 @@ class BatchProcessor
 end
 
 batch_id = BatchProcessor.process_batch([1, 2, 3, 4, 5])
-# => "V1StGXR8_Z5"
-# => Processing item V1StGXR8_Z5_000: 1
-# => Processing item V1StGXR8_Z5_001: 2
+# => "izkpm55j334u8x9y2"
+# => Processing item izkpm55j334u8x9y2_000: 1
+# => Processing item izkpm55j334u8x9y2_001: 2
 # => ...
 ```
 
@@ -417,7 +436,7 @@ end
 
 # Create a new post - opaque_id is automatically generated
 post = Post.create!(title: "Hello World", content: "This is my first post")
-puts post.opaque_id  # => "V1StGXR8_Z5jdHi6B-myT"
+puts post.opaque_id  # => "izkpm55j334u8x9y2"
 
 # Create multiple posts
 posts = Post.create!([
@@ -427,9 +446,9 @@ posts = Post.create!([
 ])
 
 posts.each { |p| puts "#{p.title}: #{p.opaque_id}" }
-# => Post 1: V1StGXR8_Z5jdHi6B-myT
-# => Post 2: Z5jdHi6B-myT12345
-# => Post 3: myT12345-ABCdefGH
+# => Post 1: izkpm55j334u8x9y2
+# => Post 2: 334u8x9y2abc1234
+# => Post 3: abc1234def5678gh
 ```
 
 #### Custom Configuration
@@ -482,7 +501,7 @@ class ApiKey < ApplicationRecord
   self.opaque_id_max_retry = 10
 end
 
-# Generated API keys will look like: "V1StGXR8Z5jdHi6BmyT1234567890AB"
+# Generated API keys will look like: "izkpm55j334u8x9y2abc1234def5678gh"
 ```
 
 ##### Short URL Configuration
@@ -529,7 +548,7 @@ class Upload < ApplicationRecord
   self.opaque_id_purge_chars = ['/', '\\', ':', '*', '?', '"', '<', '>', '|']
 end
 
-# Generated filenames will look like: "V1StGXR8-Z5jd"
+# Generated filenames will look like: "izkpm55j334u8x9y2"
 ```
 
 ##### Session Token Configuration
@@ -554,7 +573,7 @@ class Session < ApplicationRecord
   self.opaque_id_max_retry = 8
 end
 
-# Generated session tokens will look like: "V1StGXR8_Z5jdHi6B-myT123"
+# Generated session tokens will look like: "izkpm55j334u8x9y2abc123"
 ```
 
 ##### Custom Alphabet Examples
@@ -592,7 +611,7 @@ end
 
 ```ruby
 # Find by opaque ID (returns nil if not found)
-user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id("izkpm55j334u8x9y2")
 if user
   puts "Found user: #{user.name}"
 else
@@ -600,14 +619,14 @@ else
 end
 
 # Find by opaque ID (raises ActiveRecord::RecordNotFound if not found)
-user = User.find_by_opaque_id!("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id!("izkpm55j334u8x9y2")
 puts "Found user: #{user.name}"
 
 # Use in controllers for public-facing URLs
 class PostsController < ApplicationController
   def show
     @post = Post.find_by_opaque_id!(params[:id])
-    # This allows URLs like /posts/V1StGXR8_Z5jdHi6B-myT
+    # This allows URLs like /posts/izkpm55j334u8x9y2
   end
 end
 
@@ -672,8 +691,8 @@ OpaqueId provides comprehensive configuration options to customize ID generation
 - **Performance**: Longer IDs are more secure but use more storage
 - **Examples**:
   - `6` → Short URLs: `"V1StGX"`
-  - `21` → Default: `"V1StGXR8_Z5jdHi6B-myT"`
-  - `32` → API Keys: `"V1StGXR8_Z5jdHi6B-myT1234567890AB"`
+  - `18` → Default: `"izkpm55j334u8x9y2"`
+  - `32` → API Keys: `"izkpm55j334u8x9y2abc1234def5678gh"`
 
 #### `opaque_id_alphabet`
 
@@ -691,7 +710,7 @@ OpaqueId provides comprehensive configuration options to customize ID generation
 - **Purpose**: Ensures IDs start with a letter for better readability
 - **Use Cases**: When IDs are user-facing or need to be easily readable
 - **Performance**: Slight overhead due to rejection sampling
-- **Example**: `true` → `"V1StGXR8_Z5jdHi6B-myT"`, `false` → `"1StGXR8_Z5jdHi6B-myT"`
+- **Example**: `true` → `"izkpm55j334u8x9y2"`, `false` → `"zkpm55j334u8x9y2"`
 
 #### `opaque_id_purge_chars`
 
@@ -744,7 +763,7 @@ OpaqueId::ALPHANUMERIC_ALPHABET
 
 ```ruby
 OpaqueId.generate(size: 8, alphabet: OpaqueId::ALPHANUMERIC_ALPHABET)
-# => "V1StGXR8"
+# => "izkpm55j"
 ```
 
 ### `STANDARD_ALPHABET`
@@ -932,41 +951,14 @@ def generate(size:, alphabet:)
 end
 ```
 
-## Performance Benchmarks
-
-### Generation Speed (IDs per second)
-
-| Alphabet Size | Algorithm | Performance        | Relative Speed  |
-| ------------- | --------- | ------------------ | --------------- |
-| 64 characters | Fast Path | ~2,500,000 IDs/sec | 100% (baseline) |
-| 62 characters | Unbiased  | ~1,200,000 IDs/sec | 48%             |
-| 36 characters | Unbiased  | ~1,100,000 IDs/sec | 44%             |
-| 26 characters | Unbiased  | ~1,000,000 IDs/sec | 40%             |
-| 10 characters | Unbiased  | ~900,000 IDs/sec   | 36%             |
-
-_Benchmarks run on Ruby 3.2.0, generating 21-character IDs_
-
-### Memory Usage
-
-| Algorithm | Memory per ID | Memory per 1M IDs |
-| --------- | ------------- | ----------------- |
-| Fast Path | ~21 bytes     | ~21 MB            |
-| Unbiased  | ~21 bytes     | ~21 MB            |
-
-_Memory usage is consistent regardless of algorithm choice_
-
-### Collision Probability
-
-For 21-character IDs with different alphabets:
+## Performance Characteristics
 
-| Alphabet              | Characters | Collision Probability (1 in) |
-| --------------------- | ---------- | ---------------------------- |
-| STANDARD_ALPHABET     | 64         | 2.9 × 10^37                  |
-| ALPHANUMERIC_ALPHABET | 62         | 1.4 × 10^37                  |
-| Numeric (0-9)         | 10         | 1.0 × 10^21                  |
-| Binary (0-1)          | 2          | 2.1 × 10^6                   |
+OpaqueId is designed for efficient ID generation with different performance characteristics based on alphabet size:
 
-_Collision probability calculated using birthday paradox formula_
+- **64-character alphabets**: Use optimized bitwise operations for faster generation
+- **Other alphabets**: Use rejection sampling for unbiased distribution with slight overhead
+- **Memory usage**: Scales linearly with ID length
+- **Collision resistance**: Extremely low probability for typical use cases
 
 ### Performance Characteristics
 
@@ -975,7 +967,7 @@ _Collision probability calculated using birthday paradox formula_
 - **Time Complexity**: O(n) where n = ID length
 - **Space Complexity**: O(n)
 - **Rejection Rate**: 0% (no rejections)
-- **Distribution**: Perfect uniform
+- **Distribution**: Uniform distribution
 - **Best For**: High-performance applications, short URLs
 
 #### Unbiased Path (other alphabets)
@@ -983,7 +975,7 @@ _Collision probability calculated using birthday paradox formula_
 - **Time Complexity**: O(n × (1 + rejection_rate)) where rejection_rate ≈ 0.01
 - **Space Complexity**: O(n)
 - **Rejection Rate**: <1% for most alphabet sizes
-- **Distribution**: Perfect uniform (mathematically proven)
+- **Distribution**: Uniform distribution using rejection sampling
 - **Best For**: General-purpose applications, custom alphabets
 
 ### Real-World Performance

data/docs/_config.yml

@@ -1,5 +1,5 @@
 # Site settings
-title: OpaqueId Documentation
+title: OpaqueId
 description: Generate cryptographically secure, collision-free opaque IDs for ActiveRecord models
 url: "https://nyaggah.github.io"
 baseurl: "/opaque_id"
@@ -88,6 +88,8 @@ kramdown:
     block:
       line_numbers: false
       start_line: 1
+  auto_id: true
+  table_of_contents: true
 
 # Custom head includes
 head_scripts:
@@ -104,23 +106,12 @@ nav_external_links_new_tab: true
 nav_footer: true
 nav_order: 1
 
-# Header and footer
-header_links:
-  - title: "GitHub"
-    url: "https://github.com/nyaggah/opaque_id"
-  - title: "RubyGems"
-    url: "https://rubygems.org/gems/opaque_id"
-
-# Auxiliary links (moved to sidebar top)
+# Auxiliary links (appear at top right)
 aux_links:
-  - title: "GitHub"
-    url: "https://github.com/nyaggah/opaque_id"
-  - title: "RubyGems"
-    url: "https://rubygems.org/gems/opaque_id"
-  - title: "Issues"
-    url: "https://github.com/nyaggah/opaque_id/issues"
-  - title: "Releases"
-    url: "https://github.com/nyaggah/opaque_id/releases"
+  GitHub: https://github.com/nyaggah/opaque_id
+  RubyGems: https://rubygems.org/gems/opaque_id
+  Issues: https://github.com/nyaggah/opaque_id/issues
+  Releases: https://github.com/nyaggah/opaque_id/releases
 
 # Color scheme - use system theme with light fallback
 color_scheme: light

data/docs/algorithms.md

@@ -8,7 +8,10 @@ permalink: /algorithms/
 
 # Algorithms
 
-OpaqueId uses sophisticated algorithms to generate cryptographically secure, collision-free opaque IDs. This guide explains the technical details behind the generation process, optimization strategies, and mathematical foundations.
+OpaqueId builds on Ruby's built-in `SecureRandom` methods to generate cryptographically secure, collision-free opaque IDs. This guide explains the technical details behind the generation process, optimization strategies, and mathematical foundations.
+
+- TOC
+  {:toc}
 
 ## Overview
 
@@ -42,10 +45,10 @@ end
 
 ### Key Features
 
-- **Bitwise Operations**: Uses `byte & 63` instead of `byte % 64` for faster computation
+- **Bitwise Operations**: Uses `byte & 63` instead of `byte % 64` for efficient computation
 - **No Modulo Bias**: 64 is a power of 2, so bitwise AND provides uniform distribution
 - **Single Random Call**: One `SecureRandom.random_bytes(1)` call per character
-- **Maximum Performance**: Optimized for speed with 64-character alphabets
+- **Performance Optimized**: Designed for speed with 64-character alphabets
 
 ### Mathematical Foundation
 
@@ -57,7 +60,7 @@ For a 64-character alphabet:
 
 ### Performance Characteristics
 
-- **Optimized for speed**: Uses bitwise operations for maximum performance
+- **Optimized for speed**: Uses bitwise operations for efficient performance
 - **No rejection sampling**: All generated bytes are used efficiently
 - **Linear time complexity**: O(n) where n is the ID length
 

data/docs/alphabets.md

@@ -10,6 +10,9 @@ permalink: /alphabets/
 
 OpaqueId provides flexible alphabet configuration for generating IDs with different character sets. This guide covers built-in alphabets, custom alphabet creation, and best practices for alphabet selection.
 
+- TOC
+  {:toc}
+
 ## Built-in Alphabets
 
 OpaqueId comes with two pre-configured alphabets optimized for different use cases.

data/docs/api-reference.md

@@ -10,6 +10,9 @@ permalink: /api-reference/
 
 This document provides complete API documentation for OpaqueId, including all methods, classes, and configuration options.
 
+- TOC
+  {:toc}
+
 ## Core Module: OpaqueId
 
 The main module for generating opaque IDs.

data/docs/assets/css/custom.scss

@@ -292,59 +292,12 @@ table {
   color: var(--nav-child-link-color);
 }
 
-// Auxiliary links styling (top of sidebar)
-.aux-nav {
-  margin-bottom: 1.5rem;
-  padding-bottom: 1rem;
-  border-bottom: 1px solid var(--border-color-light);
-
-  .aux-nav-list {
-    list-style: none;
-    margin: 0;
-    padding: 0;
-    display: flex;
-    flex-wrap: wrap;
-    gap: 0.5rem;
-
-    .aux-nav-list-item {
-      margin: 0;
-
-      .aux-nav-list-link {
-        display: inline-flex;
-        align-items: center;
-        padding: 0.375rem 0.75rem;
-        font-size: 0.875rem;
-        font-weight: 500;
-        color: var(--aux-link-color);
-        text-decoration: none;
-        border: 1px solid var(--border-color);
-        border-radius: 6px;
-        background-color: transparent;
-        transition: all 0.2s ease;
-
-        &:hover {
-          color: var(--aux-link-hover-color);
-          border-color: var(--aux-link-hover-color);
-          background-color: rgba(168, 85, 247, 0.05);
-          text-decoration: none;
-        }
-
-        &:focus {
-          outline: 2px solid var(--aux-link-hover-color);
-          outline-offset: 2px;
-        }
-
-        // External link icon
-        &[href^="http"]:not([href*="nyaggah.github.io"]) {
-          &::after {
-            content: "↗";
-            margin-left: 0.25rem;
-            font-size: 0.75rem;
-            opacity: 0.7;
-          }
-        }
-      }
-    }
+// Simple external links styling
+.nav-list .nav-list-item .nav-list-link[href^="http"] {
+  color: var(--link-color);
+  
+  &:hover {
+    color: var(--link-color-hover);
   }
 }
 

data/docs/configuration.md

@@ -10,6 +10,9 @@ permalink: /configuration/
 
 OpaqueId provides extensive configuration options to customize ID generation for your specific needs. This guide covers all available configuration options with practical examples.
 
+- TOC
+  {:toc}
+
 ## Model-Level Configuration
 
 Configure OpaqueId on a per-model basis using class-level settings.