graphql-docs 5.2.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd0680cb4e1d09c704fe10170e4f48340b845a96ec6a91420a1b379cf7b217fd
-  data.tar.gz: dde6edd6ff1dc7c70eab9495cb7f27aacfa3e770815f8bd26c7ddbb71cc05793
+  metadata.gz: '05484c53122d5965c4c25b622e097b8e6433ba851f714e33a0b6e7d2f81c5ba5'
+  data.tar.gz: 36217b7cadfecab247ea8b52eaf15913acb5a529c6e4d7f5934ef4a69a8e147e
 SHA512:
-  metadata.gz: 71424bfe5ab2367fa0c1ac4721104dab9eda558b593293dbc46d6097bd01bfc1670a45adb4a75456f980ebb7f22eaf5b30485b3c2a2fb7b6cc7ee24e91d2bad6
-  data.tar.gz: a1ac5a15d011d9f750c15745a92e3d88a1035a729fd4a9486b159a7fa263e7a0226e3340fe262fa8624428a63d452c884ba60d262b7c51e33109b83cc3700d61
+  metadata.gz: 33d4632d6a2299c4ebff4c9865adabb28e53420013b843fc5cb6f237cfd883bd0fb959ab5406211412be417b76784b2464aaea530d51653c7bd5b1bd6f63ae33
+  data.tar.gz: 59b12439adae5c3269affccfceababd7b870e1d3a97abf08815f3a7080c84ca7170b8f4d9d1013373d3784f171267ec833a785a7781047261c78bc453456fff1

data/.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--markup-provider commonmarker
+--output-dir doc
+--protected
+--no-private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -4,6 +4,82 @@ A concise overview of the public-facing changes to the gem from version to versi
 
 ## Unreleased
 
+## v6.0.0 - 2026-01-22
+
+### Features
+
+- Add Rake task `graphql-docs:generate` for integration with Rails and other Ruby projects that use Rake. Supports both task arguments and environment variables for configuration. Can be used with `Rake::Task["assets:precompile"].enhance(["graphql-docs:generate"])` to generate docs as part of the build process.
+- Add support for running as a Rack app for easy integration with existing web applications
+- Add resizable sidebar for better UX
+- Add Dark Mode styles support
+- Render deprecation info for queries and mutations
+
+### Improvements
+
+- Replace jQuery with vanilla JavaScript for smaller bundle size and fewer dependencies
+- Optimize packaged gem size and use system fonts for better performance
+- Run CI against Ruby 4.0
+
+### Breaking Changes
+
+- **breaking:** Upgrade commonmarker, html-pipeline, and gemoji dependencies, see **BREAKING CHANGES** section below
+
+### 🚨 BREAKING CHANGES
+
+This release upgrades three major dependencies with significant breaking changes.
+
+#### Dependency Upgrades
+
+- **commonmarker**: `0.23.x` → `2.0.x` - Complete API rewrite with improved performance and standards compliance
+- **html-pipeline**: `2.14.x` → `3.0.x` - Simplified architecture, filter API changed
+- **gemoji**: `3.0.x` → `4.0.x` - Updated emoji mappings
+- **Removed**: `extended-markdown-filter` (no longer maintained, incompatible with html-pipeline 3)
+
+#### Breaking Changes for Advanced Users
+
+1. **Custom html-pipeline filters no longer work**
+   - html-pipeline 3.x has a completely different filter API
+   - If you configured custom filters via `pipeline_config[:pipeline]`, they will not work
+   - **Migration**: Rewrite custom filters using html-pipeline 3.x API (see [html-pipeline migration guide](https://github.com/jch/html-pipeline/blob/main/CHANGELOG.md))
+   - The gem now handles markdown and emoji rendering directly
+
+2. **Custom Renderer API changes**
+   - If you implemented a custom renderer that directly uses CommonMarker:
+   - **Old API**: `CommonMarker.render_html(string, :UNSAFE)`
+   - **New API**: `Commonmarker.parse(string).to_html(options: {render: {unsafe: true}})`
+   - Note the lowercase 'm' in `Commonmarker` in version 2.x
+
+3. **Table of Contents filter removed from defaults**
+   - The default `TableOfContentsFilter` is no longer applied
+   - **Migration**: Implement a custom post-processing step if needed
+
+#### What Still Works (and is Better!)
+
+- ✅ GitHub Flavored Markdown (tables, strikethrough, autolinks, task lists)
+- ✅ **Emoji rendering** - `:emoji:` syntax like `:smile:` works out of the box
+- ✅ Header anchors (automatically generated with IDs)
+- ✅ Safe and unsafe HTML rendering modes
+- ✅ Code blocks with syntax highlighting
+- ✅ All existing templates and layouts
+- ✅ Faster markdown rendering
+- ✅ More standards-compliant HTML output
+
+#### Why Upgrade?
+
+- **Security**: Updates to latest stable versions with security patches
+- **Performance**: commonmarker 2.x is significantly faster and more standards-compliant
+- **Maintainability**: All dependencies are actively maintained
+- **Modern**: Uses current Ruby ecosystem standards
+
+#### Migration Guide
+
+For most users with default configuration, this upgrade should be seamless. Advanced users should check:
+
+- [ ] Do you use custom `pipeline_config[:pipeline]` filters? → Rewrite for html-pipeline 3.x
+- [ ] Do you have a custom `Renderer` subclass that calls CommonMarker directly? → Update API calls
+- [ ] Run full test suite after upgrade
+- [ ] Regenerate documentation and visually inspect output
+
 ## v5.2.0 - 2025-02-09
 
 - Add search filter to sidebar. Thanks @denisahearn!

data/README.md

@@ -2,7 +2,12 @@
 
 Ruby library and CLI for easily generating beautiful documentation from your GraphQL schema.
 
-![sample](https://cloud.githubusercontent.com/assets/64050/23438604/6a23add0-fdc7-11e6-8852-ef41e8451033.png)
+![Screenshot of sample generated docs](https://cloud.githubusercontent.com/assets/64050/23438604/6a23add0-fdc7-11e6-8852-ef41e8451033.png)
+
+Key links:
+
+- **Demo**: [https://graphql-docs.bcodes.me](https://graphql-docs.bcodes.me).
+- **Ruby documentation**: [https://rubydoc.info/github/brettchalupa/graphql-docs.git/main](https://rubydoc.info/github/brettchalupa/graphql-docs.git/main).
 
 ## Installation
 
@@ -20,6 +25,13 @@ gem install graphql-docs
 
 ## Usage
 
+GraphQLDocs provides two ways to serve your documentation:
+
+1. **Static Site Generator (SSG)** - Pre-generate all HTML files (default)
+2. **Rack Application** - Serve documentation dynamically on-demand
+
+### Static Site Generation (SSG)
+
 GraphQLDocs can be used as a Ruby library to build the documentation website. Using it as a Ruby library allows for more control and using every supported option. Here's an example:
 
 ```ruby
@@ -50,6 +62,184 @@ See all of the supported CLI options with:
 graphql-docs -h
 ```
 
+### Rake Task
+
+GraphQLDocs includes a Rake task for integration with Rails applications and other Ruby projects that use Rake. This allows you to generate documentation as part of your build process or hook it into other Rake tasks.
+
+#### Basic Usage
+
+Using task arguments (recommended):
+
+```console
+rake graphql-docs:generate[schema.graphql]
+rake graphql-docs:generate[schema.graphql,./docs]
+rake graphql-docs:generate[schema.graphql,./docs,/api-docs,true]
+```
+
+Or using environment variables:
+
+```console
+GRAPHQL_SCHEMA_FILE=schema.graphql rake graphql-docs:generate
+```
+
+#### Available Arguments
+
+Arguments are passed in order: `[schema_file, output_dir, base_url, delete_output]`
+
+1. `schema_file` - Path to GraphQL schema file (required)
+2. `output_dir` - Output directory (default: `./output/`)
+3. `base_url` - Base URL for assets and links (default: `''`)
+4. `delete_output` - Delete output directory before generating (`true`/`false`, default: `false`)
+
+#### Available Environment Variables
+
+- `GRAPHQL_SCHEMA_FILE` - Path to GraphQL schema file (required)
+- `GRAPHQL_OUTPUT_DIR` - Output directory (default: `./output/`)
+- `GRAPHQL_BASE_URL` - Base URL for assets and links (default: `''`)
+- `GRAPHQL_DELETE_OUTPUT` - Delete output directory before generating (`true`/`false`)
+
+Note: Task arguments take precedence over environment variables.
+
+#### Example: Generate Docs Before Asset Compilation
+
+In Rails, you can automatically generate documentation before compiling assets:
+
+```ruby
+# Rakefile or lib/tasks/docs.rake
+Rake::Task["assets:precompile"].enhance(["graphql-docs:generate"])
+```
+
+Then configure using environment variables:
+
+```ruby
+# config/application.rb or .env
+ENV["GRAPHQL_SCHEMA_FILE"] = Rails.root.join("app/graphql/schema.graphql").to_s
+```
+
+Or invoke with arguments in your custom task:
+
+```ruby
+# lib/tasks/custom_docs.rake
+namespace :docs do
+  desc "Generate API documentation"
+  task :generate do
+    Rake::Task["graphql-docs:generate"].invoke(
+      "app/graphql/schema.graphql",  # schema_file
+      "public/api-docs",              # output_dir
+      "/api-docs",                    # base_url
+      "true"                          # delete_output
+    )
+  end
+end
+
+# Hook into asset compilation
+Rake::Task["assets:precompile"].enhance(["docs:generate"])
+```
+
+### Rack Application (Dynamic)
+
+For more flexibility and control, you can serve documentation dynamically using the Rack application. This is useful for:
+
+- Internal tools with frequently changing schemas
+- Integration with existing Rails/Sinatra applications
+- Adding authentication/authorization middleware
+- Dynamic schema loading from databases or APIs
+
+**Requirements**: The Rack application feature requires the `rack` gem (version 2.x or 3.x). Add it to your Gemfile:
+
+```ruby
+gem 'rack', '~> 3.0'  # or '~> 2.0' for Rack 2.x
+```
+
+The gem is compatible with both Rack 2.x and 3.x, so you can use whichever version your application requires.
+
+#### Standalone Rack App
+
+Create a `config.ru` file:
+
+```ruby
+require 'graphql-docs'
+
+schema = File.read('schema.graphql')
+
+app = GraphQLDocs::App.new(
+  schema: schema,
+  options: {
+    base_url: '',
+    use_default_styles: true,
+    cache: true  # Enable page caching
+  }
+)
+
+run app
+```
+
+Then run with:
+
+```console
+rackup config.ru
+```
+
+Visit `http://localhost:9292` to view your docs.
+
+#### Mounting in Rails
+
+```ruby
+# config/routes.rb
+require 'graphql-docs'
+
+Rails.application.routes.draw do
+  mount GraphQLDocs::App.new(schema: MyGraphQLSchema) => '/docs'
+end
+```
+
+#### Mounting in Sinatra
+
+```ruby
+require 'sinatra'
+require 'graphql-docs'
+
+schema = File.read('schema.graphql')
+docs_app = GraphQLDocs::App.new(schema: schema)
+
+map '/docs' do
+  run docs_app
+end
+
+map '/' do
+  run Sinatra::Application
+end
+```
+
+#### Rack App Features
+
+- **On-demand generation** - Pages are generated when requested
+- **Built-in caching** - Generated pages are cached in memory (disable with `cache: false`)
+- **Schema reloading** - Update schema without restarting server:
+
+```ruby
+app = GraphQLDocs::App.new(schema: schema)
+
+# Later, reload with new schema
+new_schema = File.read('updated_schema.graphql')
+app.reload_schema!(new_schema)
+```
+
+- **Asset serving** - CSS, fonts, and images served automatically
+- **Error handling** - Friendly error pages for missing types
+
+#### SSG vs Rack Comparison
+
+| Feature | SSG | Rack App |
+|---------|-----|----------|
+| Setup complexity | Low | Medium |
+| First page load | Instant | Fast (with caching) |
+| Schema updates | Manual rebuild | Automatic/reload |
+| Hosting | Any static host | Requires Ruby server |
+| Memory usage | Minimal | Higher (cached pages) |
+| Authentication | Separate layer | Built-in middleware |
+| Best for | Public docs, open source | Internal tools, dynamic schemas |
+
 ## Breakdown
 
 There are several phases going on the single `GraphQLDocs.build` call:
@@ -82,7 +272,7 @@ generator.generate
 
 By default, the HTML generation process uses ERB to layout the content. There are a bunch of default options provided for you, but feel free to override any of these. The _Configuration_ section below has more information on what you can change.
 
-It also uses [html-pipeline](https://github.com/jch/html-pipeline) to perform the rendering by default. You can override this by providing a custom rendering class.You must implement two methods:
+It uses [Commonmarker](https://github.com/gjtorikian/commonmarker) (v2.x) to perform the Markdown rendering by default, with GitHub Flavored Markdown extensions enabled including automatic header anchors. Emoji shortcodes (like `:smile:`) are automatically converted to emoji characters using [gemoji](https://github.com/github/gemoji). You can override this by providing a custom rendering class. You must implement two methods:
 
 - `initialize` - Takes two arguments, the parsed `schema` and the configuration `options`.
 - `render` Takes the contents of a template page. It also takes two optional kwargs, the GraphQL `type` and its `name`. For example:
@@ -127,6 +317,81 @@ In your ERB layouts, there are several helper methods you can use. The helper me
 
 To call these methods within templates, you must use the dot notation, such as `<%= slugify.(text) %>`.
 
+## Dark Mode Support
+
+GraphQLDocs includes built-in dark mode support that automatically adapts to the user's system preferences using the `prefers-color-scheme` media query. When a user has dark mode enabled on their operating system, the documentation will automatically display with a dark theme.
+
+### Customizing Colors
+
+The default styles use CSS custom properties (variables) for all colors, making it easy to customize the color scheme to match your brand. You can override these variables by providing a custom stylesheet.
+
+The available CSS variables are:
+
+**Light Mode (default):**
+```css
+:root {
+  --bg-primary: #fff;           /* Main background color */
+  --bg-secondary: #f8f8f8;      /* Secondary background (tables, etc.) */
+  --bg-tertiary: #fafafa;       /* Tertiary background (API boxes) */
+  --bg-code: #eee;              /* Inline code background */
+  --bg-code-block: #272822;     /* Code block background */
+  --text-primary: #444;         /* Primary text color */
+  --text-secondary: #999;       /* Secondary text (categories, etc.) */
+  --text-link: #de4f4f;         /* Link color */
+  --text-code: #525252;         /* Inline code text color */
+  --border-color: #eee;         /* Primary border color */
+  --border-color-secondary: #ddd; /* Secondary border color */
+  --shadow-color: rgba(0, 0, 0, 0.1); /* Shadow/hover effects */
+}
+```
+
+**Dark Mode:**
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-primary: #1a1a1a;
+    --bg-secondary: #252525;
+    --bg-tertiary: #2a2a2a;
+    --bg-code: #333;
+    --bg-code-block: #1e1e1e;
+    --text-primary: #e0e0e0;
+    --text-secondary: #888;
+    --text-link: #ff6b6b;
+    --text-code: #d4d4d4;
+    --border-color: #333;
+    --border-color-secondary: #444;
+    --shadow-color: rgba(255, 255, 255, 0.1);
+  }
+}
+```
+
+### Example: Custom Color Scheme
+
+To customize the colors, create a custom CSS file and load it after the default styles. You can override specific variables while keeping the rest of the defaults:
+
+```css
+/* custom-theme.css */
+:root {
+  --text-link: #0066cc;         /* Change link color to blue */
+  --bg-tertiary: #f0f0f0;       /* Lighter API boxes */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --text-link: #66b3ff;       /* Lighter blue for dark mode */
+    --bg-primary: #0d1117;      /* GitHub-like dark background */
+    --bg-secondary: #161b22;
+  }
+}
+```
+
+Then reference it in your custom template by overriding the `default` template and adding a link to your stylesheet:
+
+```html
+<link rel="stylesheet" href="<%= base_url %>/assets/style.css" />
+<link rel="stylesheet" href="<%= base_url %>/assets/custom-theme.css" />
+```
+
 ## Configuration
 
 The following options are available:
@@ -139,7 +404,7 @@ The following options are available:
 | `use_default_styles` | Indicates if you want to use the default styles.                                                                                                                                                                               | `true`                                                                                                                                                |
 | `base_url`           | Indicates the base URL to prepend for assets and links.                                                                                                                                                                        | `""`                                                                                                                                                  |
 | `delete_output`      | Deletes `output_dir` before generating content.                                                                                                                                                                                | `false`                                                                                                                                               |
-| `pipeline_config`    | Defines two sub-keys, `pipeline` and `context`, which are used by `html-pipeline` when rendering your output.                                                                                                                  | `pipeline` has `ExtendedMarkdownFilter`, `EmojiFilter`, and `TableOfContentsFilter`. `context` has `gfm: false` and `asset_root` set to GitHub's CDN. |
+| `pipeline_config`    | Defines two sub-keys, `pipeline` and `context`. The `context` hash can contain an `unsafe` key to enable raw HTML rendering (needed for custom layouts). Note: In v6.0+, markdown and emoji rendering are handled directly by the gem, not via html-pipeline filters. | `pipeline` is empty. `context` has `gfm: false`, `unsafe: true`, and `asset_root` set to GitHub's CDN. |
 | `renderer`           | The rendering class to use.                                                                                                                                                                                                    | `GraphQLDocs::Renderer`                                                                                                                               |
 | `templates`          | The templates to use when generating HTML. You may override any of the following keys: `default`, `includes`, `operations`, `objects`, `mutations`, `interfaces`, `enums`, `unions`, `input_objects`, `scalars`, `directives`. | The defaults are found in _lib/graphql-docs/layouts/_.                                                                                                |
 | `landing_pages`      | The landing page to use when generating HTML for each type. You may override any of the following keys: `index`, `query`, `object`, `mutation`, `interface`, `enum`, `union`, `input_object`, `scalar`, `directive`.           | The defaults are found in _lib/graphql-docs/landing_pages/_.                                                                                          |
@@ -195,6 +460,57 @@ The format of `schema_member_path` is a dot delimited path to the schema member.
 "Mutation.addLike" # a mutation
 ```
 
+## Browser Support
+
+The generated documentation sites work best on modern browsers. Browser requirements are determined by the CSS and JavaScript features used in the default templates.
+
+### Fully Supported Browsers
+
+All features work, including automatic dark mode based on system preferences:
+
+- **Chrome/Edge**: 79+ (January 2020)
+- **Firefox**: 67+ (May 2019)
+- **Safari**: 12.1+ (March 2019)
+- **Mobile Safari (iOS)**: 12.1+
+- **Chrome for Android**: 79+
+
+### Partial Support
+
+The documentation will display correctly, but automatic dark mode will not work:
+
+- **Chrome**: 49-78
+- **Firefox**: 31-66
+- **Safari**: 9.1-12.0
+- **Edge**: 15-78
+
+### Unsupported
+
+- **Internet Explorer**: All versions (does not support CSS custom properties)
+- **Browsers released before 2016**
+
+### Technical Requirements
+
+The default templates use the following modern web features:
+
+**CSS Features:**
+
+- CSS Custom Properties (CSS Variables) - Required for theming
+- `@media (prefers-color-scheme: dark)` - Required for automatic dark mode
+- Flexbox
+- CSS Transforms and Transitions
+
+**JavaScript Features:**
+
+- ES6+ syntax (arrow functions, `const`/`let`, template literals)
+- `sessionStorage` API - For sidebar resize persistence
+- DOM APIs: `querySelector`, `addEventListener`, etc.
+
+### Browser Support Policy
+
+- The gem targets browsers released in 2019 or later for full feature support
+- Graceful degradation ensures basic functionality on older browsers
+- Any changes that drop support for currently supported browsers will be considered breaking changes and will require a major version release
+
 ## Supported Ruby Versions
 
 The gem officially supports **Ruby 3.1 and newer**.
@@ -216,12 +532,70 @@ painless as possible.
 Upcoming work for the project is organized publicly via [GitHub
 Projects](https://github.com/users/brettchalupa/projects/7/views/1).
 
+## API Documentation
+
+This gem uses [YARD](https://yardoc.org/) for API documentation. All public classes and methods are documented with examples and detailed descriptions.
+
+### Viewing the API Documentation
+
+To generate and view the API documentation locally:
+
+```console
+bundle exec rake yard
+```
+
+This will generate HTML documentation in the `doc/` directory. Open `doc/index.html` in your browser to view it.
+
+Alternatively, you can run a live documentation server with auto-reload:
+
+```console
+bundle exec rake yard:server
+```
+
+This starts a server at http://localhost:8808 that automatically reloads when you make changes to the code.
+
+### Online Documentation
+
+The API documentation is available online at [https://rubydoc.info/github/brettchalupa/graphql-docs.git/main](https://rubydoc.info/github/brettchalupa/graphql-docs.git/main).
+
+### Documentation Coverage
+
+The codebase maintains 100% documentation coverage for all public APIs. You can check documentation statistics with:
+
+```console
+bundle exec yard stats
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `bin/rake test` to run the tests. You can also run `bin/console` for
 an interactive prompt that will allow you to experiment.
 
+### Code Style
+
+This project uses [StandardRB](https://github.com/standardrb/standard) for Ruby code style enforcement. StandardRB is a zero-configuration formatter and linter based on RuboCop.
+
+To check your code style:
+
+```console
+bundle exec rake standard
+```
+
+To automatically fix style issues:
+
+```console
+bundle exec rake standard:fix
+```
+
+The default rake task runs both StandardRB and the test suite:
+
+```console
+bundle exec rake
+```
+
+StandardRB checks are also run in CI, so make sure your code passes before opening a pull request.
+
 ### Releasing a new version of the gem
 
 1. Update CHANGELOG.md
@@ -233,20 +607,42 @@ an interactive prompt that will allow you to experiment.
 
 ## Sample Site
 
-Clone this repository and run:
+Clone this repository and try out both modes:
 
-```
+### Static Site Generation
+
+Generate the sample documentation to the `output` directory:
+
+```console
 bin/rake sample:generate
 ```
 
-to see some sample output in the `output` dir.
+Then boot up a server to view the pre-generated files:
 
-Boot up a server to view it:
+```console
+bin/rake sample:serve
+```
 
+Visit `http://localhost:5050` to view the static documentation.
+
+### Rack Application (Dynamic)
+
+Run the sample docs as a dynamic Rack application:
+
+```console
+bin/rake sample:rack
 ```
-bin/rake sample:serve
+
+Or use the config.ru directly:
+
+```console
+rackup config.ru
 ```
 
+Visit `http://localhost:9292` to view the documentation served dynamically.
+
+**Key Difference**: The SSG version pre-generates all pages (faster initial load, no runtime cost), while the Rack version generates pages on-demand (better for dynamic schemas, easier integration).
+
 ## Credits
 
 Originally built by [gjtorikian](https://github.com/gjtorikian). Actively maintained by [brettchalupa](https://github.com/brettchalupa).

data/bin/console

@@ -1,9 +1,8 @@
-#!/bin/sh
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-set -e
+puts "===> Bundling..."
+system("bin/setup", "--quiet") || exit(1)
 
-echo "===> Bundling..."
-bin/setup --quiet
-
-echo "===> Launching..."
-bin/rake console
+puts "===> Launching..."
+exec("bin/rake", "console")

data/bin/setup

@@ -1,6 +1,9 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-bundle install "$@"
+# Exit on any error
+def run_command(*args)
+  system(*args) || exit(1)
+end
+
+run_command("bundle", "install", *ARGV)

data/exe/graphql-docs

@@ -10,17 +10,17 @@ OptionParser.new do |parser|
   parser.program_name = NAME
   parser.banner = <<~EOS
 
-  Generate GraphQL docs from the passed in schema file.
+    Generate GraphQL docs from the passed in schema file.
 
-  Usage: graphql-docs SCHEMA
+    Usage: graphql-docs SCHEMA
 
-  The only required argument is the path to the schema file to generate the site from.
+    The only required argument is the path to the schema file to generate the site from.
 
-  Examples:
-    $ graphql-docs schema.graphql
-    $ graphql-docs schema.graphql -o _docs
+    Examples:
+      $ graphql-docs schema.graphql
+      $ graphql-docs schema.graphql -o _docs
 
-  Options:
+    Options:
   EOS
 
   parser.version = GraphQLDocs::VERSION
@@ -51,7 +51,7 @@ verbose = opts.delete(:verbose)
 
 puts("Generating site with the following options: #{opts}") if verbose
 
-opts.transform_keys! { |k| k.to_s.gsub("-", "_").to_sym }
+opts.transform_keys! { |k| k.to_s.tr("-", "_").to_sym }
 GraphQLDocs.build(opts)
 
-puts("Site successfully generated in: #{opts[:output_dir] || 'output' }") if verbose
+puts("Site successfully generated in: #{opts[:output_dir] || "output"}") if verbose