diff --git a/README.md b/README.md
index e4d275f823..f2cc6810de 100644
--- a/README.md
+++ b/README.md
@@ -4,16 +4,14 @@
 [![Gem Version](https://badge.fury.io/rb/rouge.svg)](https://rubygems.org/gems/rouge)
 [![YARD Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rouge-ruby.github.io/docs/)
 
-
 [Rouge][] is a pure Ruby syntax highlighter. It can highlight
-[over 200 different languages][], and output HTML or ANSI 256-color text.
-Its HTML output is compatible with stylesheets designed for [Pygments][].
-
-[Rouge]: http://rouge.jneen.net/ "Rouge"
-
-[Pygments]: http://pygments.org "Pygments"
+[over 200 different languages][languages-doc], and output HTML
+or ANSI 256-color text. Its HTML output is compatible with
+stylesheets designed for [Pygments][].
 
-[over 200 different languages]: https://rouge-ruby.github.io/docs/file.Languages.html "Languages"
+[rouge]: http://rouge.jneen.net/ "Rouge"
+[languages-doc]: docs/LANGUAGES.md "Languages"
+[pygments]: http://pygments.org "Pygments"
 
 ## Installation
 
@@ -25,8 +23,8 @@ gem 'rouge'
 
 or
 
-```bash
-$ gem install rouge
+```sh
+gem install rouge
 ```
 
 ## Usage
@@ -39,7 +37,7 @@ command line tool.
 Here's a quick example of using Rouge as you would any other regular Ruby
 library:
 
-``` ruby
+```ruby
 require 'rouge'
 
 # make some nice lexed html
@@ -62,17 +60,16 @@ used to highlight text wrapped in the `{% highlight %}` template tags. The
 use and whether to enable line numbers or not. More information is available in
 [the Jekyll docs][j-docs].
 
-[j-docs]: https://jekyllrb.com/docs/liquid/tags/#code-snippet-highlighting
-"Code snippet highlighting in the Jekyll documentation"
+[j-docs]: https://jekyllrb.com/docs/liquid/tags/#code-snippet-highlighting "Code snippet highlighting in the Jekyll documentation"
 
 ### Command Line
 
 Rouge ships with a `rougify` command which allows you to easily highlight files
 in your terminal:
 
-``` shell
-$ rougify foo.rb
-$ rougify style monokai.sublime > syntax.css
+```sh
+rougify foo.rb
+rougify style monokai.sublime > syntax.css
 ```
 
 ## Configuration
@@ -84,57 +81,60 @@ encouraged to write your own formatter if you need something custom.
 
 The built-in formatters are:
 
-* `Rouge::Formatters::HTML.new` will render your code with standard class names
+- `Rouge::Formatters::HTML.new` will render your code with standard class names
   for tokens, with no div-wrapping or other bells or whistles.
 
-* `Rouge::Formatters::HTMLInline.new(theme)` will render your code with no class
+- `Rouge::Formatters::HTMLInline.new(theme)` will render your code with no class
   names, but instead inline the styling options into the `style=` attribute.
   This is good for emails and other systems where CSS support is minimal.
 
-* `Rouge::Formatters::HTMLLinewise.new(formatter, class: 'line-%i')` will split
+- `Rouge::Formatters::HTMLLinewise.new(formatter, class: 'line-%i')` will split
   your code into lines, each contained in its own div. The `class` option will
   be used to add a class name to the div, given the line number.
 
-* `Rouge::Formatters::HTMLLineHighlighter.new(formatter, highlight_lines: [3, 5])`
+- `Rouge::Formatters::HTMLLineHighlighter.new(formatter, highlight_lines: [3, 5])`
   will split your code into lines and wrap the lines specified by the
   `highlight_lines` option in a span with a class name specified by the
   `highlight_line_class` option (default: `hll`).
 
-* `Rouge::Formatters::HTMLLineTable.new(formatter, opts={})` will output an HTML
+- `Rouge::Formatters::HTMLLineTable.new(formatter, opts={})` will output an HTML
   table containing numbered lines, each contained in its own table-row. Options
   are:
-    * `start_line: 1` - the number of the first row
-    * `line_id: 'line-%i'` - a `sprintf` template for `id` attribute with
-      current line number
-    * `line_class: 'lineno'` - a CSS class for each table-row
-    * `table_class: 'rouge-line-table'` - a CSS class for the table
-    * `gutter_class: 'rouge-gutter'` - a CSS class for the line-number cell
-    * `code_class: 'rouge-code'` - a CSS class for the code cell
-
-* `Rouge::Formatters::HTMLPygments.new(formatter, css_class='codehilite')` wraps
+
+  - `start_line: 1` - the number of the first row
+  - `line_id: 'line-%i'` - a `sprintf` template for `id` attribute with
+    current line number
+  - `line_class: 'lineno'` - a CSS class for each table-row
+  - `table_class: 'rouge-line-table'` - a CSS class for the table
+  - `gutter_class: 'rouge-gutter'` - a CSS class for the line-number cell
+  - `code_class: 'rouge-code'` - a CSS class for the code cell
+
+- `Rouge::Formatters::HTMLPygments.new(formatter, css_class='codehilite')` wraps
   the given formatter with div wrappers generally expected by stylesheets
   designed for Pygments.
 
-* `Rouge::Formatters::HTMLTable.new(formatter, opts={})` will output an HTML
+- `Rouge::Formatters::HTMLTable.new(formatter, opts={})` will output an HTML
   table containing numbered lines similar to `Rouge::Formatters::HTMLLineTable`,
   except that the table from this formatter has just a single table-row.
   Therefore, while the table is more DOM-friendly for JavaScript scripting, long
   code lines will mess with the column alignment. Options are:
-    * `start_line: 1` - the number of the first line
-    * `line_format: '%i'` - a `sprintf` template for the line number itself
-    * `table_class: 'rouge-table'` - a CSS class for the table
-    * `gutter_class: 'rouge-gutter'` - a CSS class for the gutter
-    * `code_class: 'rouge-code'` - a CSS class for the code column
 
-* `Rouge::Formatters::HTMLLegacy.new(opts={})` is a backwards-compatibility
+  - `start_line: 1` - the number of the first line
+  - `line_format: '%i'` - a `sprintf` template for the line number itself
+  - `table_class: 'rouge-table'` - a CSS class for the table
+  - `gutter_class: 'rouge-gutter'` - a CSS class for the gutter
+  - `code_class: 'rouge-code'` - a CSS class for the code column
+
+- `Rouge::Formatters::HTMLLegacy.new(opts={})` is a backwards-compatibility
   class intended for users of Rouge 1.x, with options that were supported then.
   Options are:
-    * `inline_theme: nil` - use an HTMLInline formatter with the given theme
-    * `line_numbers: false` - use an HTMLTable formatter
-    * `wrap: true` - use an HTMLPygments wrapper
-    * `css_class: 'codehilite'` - a CSS class to use for the Pygments wrapper
 
-* `Rouge::Formatters::Terminal256.new(theme)` is a formatter for generating
+  - `inline_theme: nil` - use an HTMLInline formatter with the given theme
+  - `line_numbers: false` - use an HTMLTable formatter
+  - `wrap: true` - use an HTMLPygments wrapper
+  - `css_class: 'codehilite'` - a CSS class to use for the Pygments wrapper
+
+- `Rouge::Formatters::Terminal256.new(theme)` is a formatter for generating
   highlighted text for use in the terminal. `theme` must be an instance of
   `Rouge::Theme`, or a `Hash` structure with `:theme` entry.
 
@@ -145,7 +145,7 @@ of the HTML document, we suggest writing your own HTML formatter. This can be
 accomplished by subclassing `Rouge::Formatters::HTML` and overriding specific
 methods:
 
-``` ruby
+```ruby
 class MyFormatter < Rouge::Formatters::HTML
 
   # this is the main entry method. override this to customize the behavior of
@@ -189,16 +189,16 @@ end
 
 ### Lexer Options
 
-* `debug: false` will print a trace of the lex on stdout.
+- `debug: false` will print a trace of the lex on stdout.
 
-* `parent: ''` allows you to specify which language the template is inside.
+- `parent: ''` allows you to specify which language the template is inside.
 
 ### CSS Options
 
-* `scope: '.highlight'` sets the CSS selector to which styles are applied,
+- `scope: '.highlight'` sets the CSS selector to which styles are applied,
   e.g.:
 
-  ``` ruby
+  ```ruby
   Rouge::Themes::MonokaiSublime.render(scope: 'code')
   ```
 
@@ -222,16 +222,16 @@ different encoding, please convert it to UTF-8 first.
 
 ## Integrations
 
-* Middleman:
-  * [middleman-syntax][] (@bhollis)
-  * [middleman-rouge][] (@Linuus)
-* RDoc: [rdoc-rouge][] (@zzak)
-* Rails: [Rouge::Rails][] (@jacobsimeon)
+- Middleman:
+  - [middleman-syntax][] (@bhollis)
+  - [middleman-rouge][] (@Linuus)
+- RDoc: [rdoc-rouge][] (@zzak)
+- Rails: [Rouge::Rails][] (@jacobsimeon)
 
 [middleman-syntax]: https://github.com/middleman/middleman-syntax
 [middleman-rouge]: https://github.com/Linuus/middleman-rouge
 [rdoc-rouge]: https://github.com/zzak/rdoc-rouge
-[Rouge::Rails]: https://github.com/jacobsimeon/rouge-rails
+[rouge::rails]: https://github.com/jacobsimeon/rouge-rails
 
 ## Contributing
 
@@ -242,14 +242,12 @@ developing new lexers.
 
 ### Bug Reports
 
-Rouge uses GitHub's Issues to report bugs. You can [choose][issue_chooser] from
+Rouge uses GitHub's Issues to report bugs. You can [choose][issue-chooser] from
 one of our templates or create a custom issue. Issues that have not been active
 for a year are automatically closed by GitHub's [Probot][].
 
-[issue_chooser]: https://github.com/rouge-ruby/rouge/issues/new/choose
-"Choose an issue from the templates"
-
-[Probot]: https://probot.github.io "Read more about GitHub's Probot"
+[issue-chooser]: https://github.com/rouge-ruby/rouge/issues/new/choose "Choose an issue from the templates"
+[probot]: https://probot.github.io "Read more about GitHub's Probot"
 
 ### Developing Lexers
 
@@ -260,8 +258,7 @@ We want to make it as easy as we can for anyone to contribute a lexer to Rouge.
 To help get you started, we have [a shiny new guide][lexer-dev-doc] on lexer
 development in the documentation. The best place is to start there.
 
-[lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html
-"Rouge's lexer development guide"
+[lexer-dev-doc]: https://rouge-ruby.github.io/docs/file.LexerDevelopment.html "Rouge's lexer development guide"
 
 If you get stuck and need help, submit a pull request with what you have and
 make it clear in your submission that the lexer isn't finished yet. We'll do our
@@ -273,11 +270,11 @@ with actual code.
 Once you've cloned the repository from GitHub, you can test the core of Rouge
 simply by running `rake` (no `bundle exec` required). You can also run a single
 test file by setting the `TEST` environment variable to the path of the desired
-test. For example, to test just the *`ruby` lexer* (located at path
+test. For example, to test just the _`ruby` lexer_ (located at path
 `spec/lexers/ruby_spec.rb`) simply run the following:
 
-``` shell
-$ TEST=spec/lexers/ruby_spec.rb rake
+```sh
+TEST=spec/lexers/ruby_spec.rb rake
 ```
 
 To test a lexer visually, run `rackup` from the top-level working directory and