From c57c96a1b408bd8e920eb399e570809f9179a2b9 Mon Sep 17 00:00:00 2001
From: Jonas Mueller <jonas@tigger.cloud>
Date: Sat, 6 Sep 2025 20:32:48 +0200
Subject: [PATCH 1/2] Add `rake rdoc`

---
 .gitignore |  2 +-
 Rakefile   | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index b982e7e..45a09a6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,7 +3,7 @@
 /vendor
 /.bundle
 /.yardoc
-/doc
+/rdoc
 .sass-cache
 /tilt-*.gem
 /coverage
diff --git a/Rakefile b/Rakefile
index 1fff71c..812ab53 100644
--- a/Rakefile
+++ b/Rakefile
@@ -5,6 +5,28 @@ task :test do
   sh "#{FileUtils::RUBY} #{"-w" if RUBY_VERSION >= '3'} #{'-W:strict_unused_block' if RUBY_VERSION >= '3.4'} test/all.rb"
 end
 
+desc "Generate rdoc"
+task :rdoc do
+  rdoc_dir = "rdoc"
+  rdoc_opts = ["--line-numbers", '--title', 'Tilt']
+
+  begin
+    gem 'hanna'
+    rdoc_opts.concat(['-f', 'hanna'])
+  rescue Gem::LoadError
+  end
+
+  rdoc_opts.concat(['--main', 'README.md', "-o", rdoc_dir] +
+    %w"README.md CHANGELOG.md COPYING" +
+    Dir["lib/**/*.rb"]
+  )
+
+  FileUtils.rm_rf(rdoc_dir)
+
+  require "rdoc"
+  RDoc::RDoc.new.document(rdoc_opts)
+end
+
 desc "Run tests with coverage"
 task :test_cov do
   ENV['COVERAGE'] = '1'

From 10ee4b5319851e6b427ef3499478a6d7d65344a2 Mon Sep 17 00:00:00 2001
From: Jonas Mueller <jonas@tigger.cloud>
Date: Wed, 11 Jun 2025 16:21:36 +0200
Subject: [PATCH 2/2] Extract template documentation into lib/tilt/*.rb

The main template table in README.md links to these via rdoc-ref.

Remove TEMPLATES.md and convert docs from markdown to rdoc syntax.
---
 README.md                | 161 ++++++------
 docs/TEMPLATES.md        | 519 ---------------------------------------
 lib/tilt/asciidoc.rb     |  17 +-
 lib/tilt/babel.rb        |   5 +
 lib/tilt/builder.rb      |   4 +
 lib/tilt/coffee.rb       |  17 +-
 lib/tilt/commonmarker.rb |  41 ++++
 lib/tilt/creole.rb       |  10 +-
 lib/tilt/csv.rb          |  60 +++--
 lib/tilt/erb.rb          |  69 +++++-
 lib/tilt/erubi.rb        |  49 +++-
 lib/tilt/etanni.rb       |   7 +
 lib/tilt/haml.rb         |  68 ++++-
 lib/tilt/kramdown.rb     |  48 +++-
 lib/tilt/liquid.rb       |  76 +++++-
 lib/tilt/livescript.rb   |  15 +-
 lib/tilt/mapping.rb      |  14 +-
 lib/tilt/markaby.rb      |  13 +-
 lib/tilt/nokogiri.rb     |  15 +-
 lib/tilt/pandoc.rb       |  44 +++-
 lib/tilt/pipeline.rb     |   1 +
 lib/tilt/plain.rb        |   6 +-
 lib/tilt/prawn.rb        |  20 +-
 lib/tilt/radius.rb       |  55 +++++
 lib/tilt/rdiscount.rb    |  71 +++++-
 lib/tilt/rdoc.rb         |  24 +-
 lib/tilt/redcarpet.rb    |  42 ++++
 lib/tilt/redcloth.rb     |  29 ++-
 lib/tilt/rst-pandoc.rb   |  25 +-
 lib/tilt/sass.rb         |  18 +-
 lib/tilt/slim.rb         |  13 +
 lib/tilt/string.rb       |  12 +-
 lib/tilt/template.rb     |  10 +-
 lib/tilt/typescript.rb   |   5 +
 lib/tilt/yajl.rb         |  82 ++++---
 35 files changed, 934 insertions(+), 731 deletions(-)
 delete mode 100644 docs/TEMPLATES.md

diff --git a/README.md b/README.md
index 9dc79c6..b5e1e62 100644
--- a/README.md
+++ b/README.md
@@ -21,60 +21,57 @@ template engines included in the distribution.
 
 Support for these template engines is included with Tilt:
 
-| Engine               | File Extensions        | Required Libraries            |
-| ---------------------| -----------------------| ------------------------------|
-| Asciidoctor          | .ad, .adoc, .asciidoc  | asciidoctor                   |
-| Babel                | .es6, .babel, .jsx     | babel-transpiler              |
-| Builder              | .builder               | builder                       |
-| CoffeeScript         | .coffee                | coffee-script (+ javascript)  |
-| CoffeeScriptLiterate | .litcoffee             | coffee-script (+ javascript)  |
-| CommonMarker         | .markdown, .mkd, .md   | commonmarker                  |
-| Creole               | .wiki, .creole         | creole                        |
-| CSV                  | .rcsv                  | csv (ruby stdlib)             |
-| ERB                  | .erb, .rhtml           | erb (ruby stdlib)             |
-| Erubi                | .erb, .rhtml, .erubi   | erubi                         |
-| Etanni               | .ern, .etanni          | none                          |
-| Haml                 | .haml                  | haml                          |
-| Kramdown             | .markdown, .mkd, .md   | kramdown                      |
-| Liquid               | .liquid                | liquid                        |
-| LiveScript           | .ls                    | livescript (+ javascript)     |
-| Markaby              | .mab                   | markaby                       |
-| Nokogiri             | .nokogiri              | nokogiri                      |
-| Pandoc               | .markdown, .mkd, .md   | pandoc                        |
-| Plain                | .html                  | none                          |
-| Prawn                | .prawn                 | prawn                         |
-| Radius               | .radius                | radius                        |
-| RDiscount            | .markdown, .mkd, .md   | rdiscount                     |
-| RDoc                 | .rdoc                  | rdoc                          |
-| Redcarpet            | .markdown, .mkd, .md   | redcarpet                     |
-| RedCloth             | .textile               | redcloth                      |
-| RstPandoc            | .rst                   | pandoc                        |
-| Slim                 | .slim                  | slim                          |
-| Sass                 | .sass                  | sass-embedded, sassc, or sass |
-| Scss                 | .scss                  | sass-embedded, sassc, or sass |
-| String               | .str                   | none                          |
-| TypeScript           | .ts                    | typescript (+ javascript)     |
-| Yajl                 | .yajl                  | yajl-ruby                     |
-
-See [TEMPLATES.md][t] for detailed information on template engine
+| Engine                                            | File Extensions         | Required Libraries             |
+| ------------------------------------------------- | ----------------------- | ------------------------------ |
+| {Asciidoctor}[rdoc-ref:lib/tilt/asciidoc.rb]      | .ad, .adoc, .asciidoc   | asciidoctor                    |
+| {Babel}[rdoc-ref:lib/tilt/babel.rb]               | .es6, .babel, .jsx      | babel-transpiler               |
+| {Builder}[rdoc-ref:lib/tilt/builder.rb]           | .builder                | builder                        |
+| {CoffeeScript}[rdoc-ref:lib/tilt/coffee.rb]       | .coffee                 | coffee-script (+ javascript)   |
+| CoffeeScriptLiterate                              | .litcoffee              | coffee-script (+ javascript)   |
+| {CommonMarker}[rdoc-ref:lib/tilt/commonmarker.rb] | .markdown, .mkd, .md    | commonmarker                   |
+| {Creole}[rdoc-ref:lib/tilt/creole.rb]             | .wiki, .creole          | creole                         |
+| {CSV}[rdoc-ref:lib/tilt/csv.rb]                   | .rcsv                   | csv (ruby stdlib)              |
+| {ERB}[rdoc-ref:lib/tilt/erb.rb]                   | .erb, .rhtml            | erb (ruby stdlib)              |
+| {Erubi}[rdoc-ref:lib/tilt/erubi.rb]               | .erb, .rhtml, .erubi    | erubi                          |
+| {Etanni}[rdoc-ref:lib/tilt/etanni.rb]             | .ern, .etanni           | none                           |
+| {Haml}[rdoc-ref:lib/tilt/haml.rb]                 | .haml                   | haml                           |
+| {Kramdown}[rdoc-ref:lib/tilt/kramdown.rb]         | .markdown, .mkd, .md    | kramdown                       |
+| {Liquid}[rdoc-ref:lib/tilt/liquid.rb]             | .liquid                 | liquid                         |
+| {LiveScript}[rdoc-ref:lib/tilt/livescript.rb]     | .ls                     | livescript (+ javascript)      |
+| {Markaby}[rdoc-ref:lib/tilt/markaby.rb]           | .mab                    | markaby                        |
+| {Nokogiri}[rdoc-ref:lib/tilt/nokogiri.rb]         | .nokogiri               | nokogiri                       |
+| {Pandoc}[rdoc-ref:lib/tilt/pandoc.rb]             | .markdown, .mkd, .md    | pandoc                         |
+| {Plain}[rdoc-ref:lib/tilt/plain.rb]               | .html                   | none                           |
+| {Prawn}[rdoc-ref:lib/tilt/prawn.rb]               | .prawn                  | prawn                          |
+| {Radius}[rdoc-ref:lib/tilt/radius.rb]             | .radius                 | radius                         |
+| {RDiscount}[rdoc-ref:lib/tilt/rdiscount.rb]       | .markdown, .mkd, .md    | rdiscount                      |
+| {RDoc}[rdoc-ref:lib/tilt/rdoc.rb]                 | .rdoc                   | rdoc                           |
+| {Redcarpet}[rdoc-ref:lib/tilt/redcarpet.rb]       | .markdown, .mkd, .md    | redcarpet                      |
+| {RedCloth}[rdoc-ref:lib/tilt/redcloth.rb]         | .textile                | redcloth                       |
+| {RstPandoc}[rdoc-ref:lib/tilt/rst-pandoc.rb]      | .rst                    | pandoc                         |
+| {Slim}[rdoc-ref:lib/tilt/slim.rb]                 | .slim                   | slim                           |
+| {Sass}[rdoc-ref:lib/tilt/sass.rb]                 | .sass                   | sass-embedded, sassc, or sass  |
+| Scss                                              | .scss                   | sass-embedded, sassc, or sass  |
+| {String}[rdoc-ref:lib/tilt/string.rb]             | .str                    | none                           |
+| {TypeScript}[rdoc-ref:lib/tilt/typescript.rb]     | .ts                     | typescript (+ javascript)      |
+| {Yajl}[rdoc-ref:lib/tilt/yajl.rb]                 | .yajl                   | yajl-ruby                      |
+
+See the linked files under `./lib/tilt/*.rb` for detailed information on template engine
 options and supported features.
 
-[t]: http://github.com/jeremyevans/tilt/blob/master/docs/TEMPLATES.md
-   "Tilt Template Engine Documentation"
-
 Basic Usage
 -----------
 
 Instant gratification:
 
-~~~ruby
+``` ruby
 require 'tilt'
 require 'tilt/erb'
 template = Tilt.new('templates/foo.erb')
 => #<Tilt::ERBTemplate @file="templates/foo.erb" ...>
 output = template.render
 => "Hello world!"
-~~~
+```
 
 It's recommended that calling programs explicitly require the Tilt template
 engine libraries (like 'tilt/erb' above) at load time. Tilt attempts to
@@ -87,22 +84,22 @@ creation and rendering. In the instant gratification example, we let Tilt
 determine the template implementation class based on the filename, but
 Tilt::Template implementations can also be used directly:
 
-~~~ruby
+``` ruby
 require 'tilt/haml'
 template = Tilt::HamlTemplate.new('templates/foo.haml')
 output = template.render
-~~~
+```
 
 The `render` method takes an optional evaluation scope and locals hash
 arguments. Here, the template is evaluated within the context of the
 `Person` object with locals `x` and `y`:
 
-~~~ruby
+``` ruby
 require 'tilt/erb'
 template = Tilt::ERBTemplate.new('templates/foo.erb')
 joe = Person.find('joe')
 output = template.render(joe, :x => 35, :y => 42)
-~~~
+```
 
 If no scope is provided, the template is evaluated within the context of an
 object created with `Object.new`.
@@ -111,26 +108,26 @@ A single `Template` instance's `render` method may be called multiple times
 with different scope and locals arguments. Continuing the previous example,
 we render the same compiled template but this time in jane's scope:
 
-~~~ruby
+``` ruby
 jane = Person.find('jane')
 output = template.render(jane, :x => 22, :y => nil)
-~~~
+```
 
 Blocks can be passed to `render` for templates that support running
 arbitrary ruby code (usually with some form of `yield`). For instance,
 assuming the following in `foo.erb`:
 
-~~~ruby
+``` ruby
 Hey <%= yield %>!
-~~~
+```
 
 The block passed to `render` is called on `yield`:
 
-~~~ruby
+``` ruby
 template = Tilt::ERBTemplate.new('foo.erb')
 template.render { 'Joe' }
 # => "Hey Joe!"
-~~~
+```
 
 Fixed Locals
 ------------
@@ -155,38 +152,38 @@ should start and end with parentheses. For example, if the template does not
 use local variables, you can set it to `"()"`.  This will cause an ArgumentError
 to be raised if you call the template with locals:
 
-~~~ruby
+``` ruby
 template = Tilt::ERBTemplate.new('templates/foo.erb', fixed_locals: "()")
 output = template.render(Object.new) # No ArgumentError
 output = template.render(Object.new, x: 1) # ArgumentError
-~~~
+```
 
 If the template must be passed the `x` local variable to work correctly, and
 optionally can be provided the `y` local variable:
 
-~~~ruby
+``` ruby
 template = Tilt::ERBTemplate.new('templates/foo.erb', fixed_locals: "(x:, y: nil)")
 output = template.render(Object.new) # ArgumentError
 output = template.render(Object.new, x: 1) # No ArgumentError
 output = template.render(Object.new, x: 1, y: 2) # No ArgumentError
 output = template.render(Object.new, x: 1, y: 2, z: 3) # ArgumentError
-~~~
+```
 
 If the template wants to accept arbitrary local variables, in order to pass
 the variables to a method inside the template, you can provide a keyword splat
 or a single positional argument (with an optional empty hash value if you want
 to support being called with no local variables):
 
-~~~ruby
+``` ruby
 template = Tilt::ERBTemplate.new('templates/foo.erb', fixed_locals: "(**args)") # or "(args={})"
-~~~
+```
 
 If you would like to name the block passed to the template, so you can pass
 it to a method inside the template:
 
-~~~ruby
+``` ruby
 template = Tilt::ERBTemplate.new('templates/foo.erb', fixed_locals: "(&block)")
-~~~
+```
 
 Embedded Fixed Locals
 ---------------------
@@ -197,9 +194,9 @@ and others, it can be helpful to embed the fixed locals inside the template
 using a magic comment.  This can be enabled using the `:extract_fixed_locals`
 template option.  It can also be enabled globally via:
 
-~~~ruby
+``` ruby
 Tilt.extract_fixed_locals = true
-~~~
+```
 
 If `:extract_fixed_locals` option is given, or extraction is globally enabled,
 and the `:fixed_locals` option is not provided when creating the template,
@@ -216,6 +213,12 @@ In ERB templates, you can use the following comment format:
 <%# locals: () %>
 ```
 
+In slim templates, the comment format looks like this:
+
+```
+//# locals: ()
+```
+
 In string templates, it is a little ackward, but still possible (note that the
 closing `}` goes on a separate line:
 
@@ -267,29 +270,29 @@ table of template engines above.
 The Tilt.register method associates a filename pattern with a specific
 template implementation. To use ERB for files ending in a `.bar` extension:
 
-~~~ruby
+``` ruby
 >> Tilt.register Tilt::ERBTemplate, 'bar'
 >> Tilt.new('views/foo.bar')
 => #<Tilt::ERBTemplate @file="views/foo.bar" ...>
-~~~
+```
 
 Retrieving the template class for a file or file extension:
 
-~~~ruby
+``` ruby
 >> Tilt['foo.bar']
 => Tilt::ERBTemplate
 >> Tilt['haml']
 => Tilt::HamlTemplate
-~~~
+```
 
 Retrieving a list of template classes for a file:
 
-~~~ruby
+``` ruby
 >> Tilt.templates_for('foo.bar')
 => [Tilt::ERBTemplate]
 >> Tilt.templates_for('foo.haml.bar')
 => [Tilt::ERBTemplate, Tilt::HamlTemplate]
-~~~
+```
 
 The template class is determined by searching for a series of decreasingly
 specific name patterns. When creating a new template with
@@ -311,7 +314,7 @@ want to customize the output per different locals.  For example, let's
 say you have an scss file that you want to allow customization with
 erb, such as:
 
-~~~scss
+```scss
 .foo {
   .bar {
     .<%= hide_class %> {
@@ -319,27 +322,27 @@ erb, such as:
     }
   }
 }
-~~~
+```
 
 You can do this manually:
 
-~~~ruby
+``` ruby
 scss = Tilt.new("file.scss.erb").render(nil, hide_class: 'baz')
 css = Tilt.new("scss"){scss}.render
-~~~
+```
 
 A more automated way to handle it is to register a template pipeline:
 
-~~~ruby
+``` ruby
   Tilt.register_pipeline("scss.erb")
-~~~
+```
 
 Then Tilt will automatically take the output of the erb engine,
 and pass it to the scss engine, automating the above code.
 
-~~~ruby
+``` ruby
   css = Tilt.new("file.scss.erb").render(nil, hide_class: 'baz')
-~~~
+```
 
 Finalizing Mappings
 -------------------
@@ -356,7 +359,7 @@ and then freeze the mappings. Tilt.finalize! will replace Tilt's default
 mapping with a finalized versions, as well as freeze Tilt so that no
 further changes can be made.
 
-~~~ruby
+``` ruby
 require 'tilt/erubi'
 require 'tilt/string'
 require 'tilt/sass'
@@ -365,7 +368,7 @@ Tilt['erb'] # => Tilt::ErubiTemplate
 Tilt['str'] # => Tilt::StringTemplate
 Tilt['scss'] # => Tilt::ScssTemplate
 Tilt['haml'] # => nil # even if haml is installed
-~~~
+```
 
 Encodings
 ---------
@@ -380,9 +383,9 @@ recommend setting this option. When providing a custom reader block (`Tilt.new
 Most of the template engines in Tilt also allows you to override the encoding
 using the `:default_encoding`-option:
 
-~~~ruby
+``` ruby
 tmpl = Tilt.new('hello.erb', :default_encoding => 'Big5')
-~~~
+```
 
 Ultimately it's up to the template engine how to handle the encoding: It might
 respect `:default_encoding`, it might always assume it's UTF-8 (like
diff --git a/docs/TEMPLATES.md b/docs/TEMPLATES.md
deleted file mode 100644
index 64805a1..0000000
--- a/docs/TEMPLATES.md
+++ /dev/null
@@ -1,519 +0,0 @@
-Tilt Templates
-==============
-
-While all Tilt templates use the same basic interface for template loading and
-evaluation, each varies in its capabilities and available options. Detailed
-documentation on each supported template engine is provided below.
-
-There are also some file extensions that have several implementations
-(currently ERB and Markdown). These template classes have certain features
-which are guaranteed to work across all the implementations. If you wish to be
-compatible with all of these template classes, you should only depend on the
-cross-implementation features.
-
- * [ERB](#erb) - Generic ERB implementation (backed by erb.rb or Erubi)
- * [erb.rb](#erbrb) - `Tilt::ERBTemplate`
- * [Erubi](#erubi) - `Tilt::ErubiTemplate`
- * [Haml](#haml) - `Tilt::HamlTemplate`
- * [Liquid](#liquid) - `Tilt::LiquidTemplate`
- * Nokogiri - `Tilt::NokogiriTemplate`
- * Builder - `Tilt::BuilderTemplate`
- * Markaby - `Tilt::MarkabyTemplate`
- * [Radius](#radius) - `Tilt::RadiusTemplate`
-
-Tilt also includes support for CSS processors like [Sass][sass],
-[CoffeeScript][coffee-script] and some simple text formats.
-
- * Sass - `Tilt::SassTemplate`
- * Scss - `Tilt::ScssTemplate`
- * CoffeeScript - `Tilt::CoffeeScriptTemplate`
- * Literate CoffeeScript - `Tilt::CoffeeScriptLiterateTemplate`
- * LiveScript - `Tilt::LiveScriptTemplate`
- * [Textile](#redcloth) - `Tilt::RedClothTemplate`
- * reStructuredText - `Tilt::RstPandocTemplate`
- * Creole - `Tilt::CreoleTemplate`
- * [RDoc](#rdoc) - `Tilt::RDocTemplate`
-
-Tilt has extensive support for Markdown, backed by one of seven different
-implementations (depending on which are available on your system):
-
- * [Markdown](#markdown) - Generic Markdown implementation
- * [RDiscount](#rdiscount) - `Tilt::RDiscountTemplate`
- * Redcarpet - `Tilt::RedcarpetTemplate`
- * Kramdown - `Tilt::KramdownTemplate`
- * Pandoc - `Tilt::PandocTemplate`
- * CommonMarker - `Tilt::CommonMarkerTemplate`
-
-<a name='erb'></a>
-ERB (`erb`, `rhtml`)
---------------------
-
-ERB is a simple but powerful template languge for Ruby. In Tilt it's backed by
-[Erubi](#erubi) (if installed on your system) or by
-[erb.rb](#erbrb) (which
-is included in Ruby's standard library). This documentation applies to all three
-implementations.
-
-### Example
-
-    Hello <%= world %>!
-
-### Usage
-
-ERB templates support custom evaluation scopes and locals:
-
-    >> require 'erb'
-    >> template = Tilt.new('hello.html.erb')
-    >> template.render(self, :world => 'World!')
-    => "Hello World!"
-
-Or, use `Tilt['erb']` directly to process strings:
-
-    template = Tilt['erb'].new { "Hello <%= world %>!" }
-    template.render(self, :world => 'World!')
-
-### Options
-
-#### `:trim => trim`
-
-Omits newlines and spaces around certain lines (usually those that starts with
-`<%` and ends with `%>`). There isn't a specification for how trimming in ERB
-should work, so if you need more control over the whitespace, you should use
-[erb.rb](#erbrb) or [Erubi](#erubi) directly.
-
-
-#### `:outvar => '_erbout'`
-
-The name of the variable used to accumulate template output. This can be
-any valid Ruby expression but must be assignable. By default a local
-variable named `_erbout` is used.
-
-#### `:freeze => false`
-
-If set to true, will set the `frozen_string_literal` flag in the compiled
-template code, so that string literals inside the templates will be frozen.
-
-<a name='erbrb'></a>
-erb.rb (`erb`, `rhtml`)
------------------------
-
-[ERB](#erb) implementation available in Ruby's standard library.
-
-All the documentation of [ERB](#erb) applies in addition to the following:
-
-### Usage
-
-The `Tilt::ERBTemplate` class is registered for all files ending in `.erb` or
-`.rhtml` by default, but with a *lower* priority than ErubiTemplate.
-If you specifically want to use ERB, it's recommended to use
-`#prefer`:
-
-    Tilt.prefer Tilt::ERBTemplate
-
-__NOTE:__ It's suggested that your program `require 'erb'` at load time when
-using this template engine within a threaded environment.
-
-### Options
-
-#### `:trim => true`
-
-The ERB trim mode flags. This is a string consisting of any combination of the
-following characters:
-
-  * `'>'`  omits newlines for lines ending in `>`
-  * `'<>'` omits newlines for lines starting with `<%` and ending in `%>`
-  * `'%'`  enables processing of lines beginning with `%`
-  * `true` is an alias of `<>`
-
-### See also
-
-  * [ERB documentation](https://docs.ruby-lang.org/en/master/ERB.html)
-
-
-<a name='erubi'></a>
-Erubi (`erb`, `rhtml`, `erubi`)
----------------------------------
-
-[Erubi][erubi] is an ERB implementation that uses the same algorithm as
-the erubis gem, but is maintained and offers numerous improvements.
-
-All the documentation of [ERB](#erb) applies in addition to the following:
-
-### Usage
-
-The `Tilt::ErubiTemplate` class is registered for all files ending in `.erb` or
-`.rhtml` by default, with the *highest* priority.
-
-__NOTE:__ It's suggested that your program `require 'erubi'` at load time when
-using this template engine within a threaded environment.
-
-### Options
-
-#### `:engine_class => Erubi::Engine`
-
-Allows you to specify a custom engine class to use instead of the
-default which is `Erubi::Engine`.
-
-#### Other
-
-Other options are passed to the constructor of the engine class.
-
-### See also
-
-  * [Erubi Home][erubi]
-
-
-<a name='haml'></a>
-Haml (`haml`)
--------------
-
-[Haml][haml] is a markup language that’s used to cleanly and simply describe
-the HTML of any web document without the use of inline code. Haml functions as
-a replacement for inline page templating systems such as PHP, ASP, and ERB, the
-templating language used in most Ruby on Rails applications. However, Haml
-avoids the need for explicitly coding HTML into the template, because it itself
-is a description of the HTML, with some code to generate dynamic content.
-([more](http://haml.info/about.html))
-
-
-### Example
-
-    %html
-      %head
-        %title= @title
-      %body
-        %h1
-          Hello
-          = world + '!'
-
-### Usage
-
-The `Tilt::HamlTemplate` class is registered for all files ending in `.haml`
-by default. Haml templates support custom evaluation scopes and locals:
-
-    >> require 'haml'
-    >> template = Tilt.new('hello.haml')
-    => #<Tilt::HamlTemplate @file='hello.haml'>
-    >> @title = "Hello Haml!"
-    >> template.render(self, :world => 'Haml!')
-    => "
-    <html>
-      <head>
-        <title>Hello Haml!</title>
-      </head>
-      <body>
-        <h1>Hello Haml!</h1>
-      </body>
-    </html>"
-
-Or, use the `Tilt::HamlTemplate` class directly to process strings:
-
-    >> require 'haml'
-    >> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
-    => #<Tilt::HamlTemplate @file=nil ...>
-    >> template.render
-    => "<h1>Hello Haml!</h1>"
-
-__NOTE:__ It's suggested that your program `require 'haml'` at load time when
-using this template engine within a threaded environment.
-
-### Options
-
-Please see the [Haml Reference](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html#options) for all available options.
-
-### See also
-
-  * [#haml.docs](http://haml.info/docs.html)
-  * [Haml Tutorial](http://haml.info/tutorial.html)
-  * [Haml Reference](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html)
-
-
-<a name='liquid'></a>
-Liquid (`liquid`)
------------------
-
-[Liquid][liquid] is for rendering safe templates which cannot affect the
-security of the server they are rendered on.
-
-### Example
-
-    <html>
-      <head>
-        <title>{{ title }}</title>
-      </head>
-      <body>
-        <h1>Hello {{ world }}!</h1>
-      </body>
-    </html>
-
-### Usage
-
-`Tilt::LiquidTemplate` is registered for all files ending in `.liquid` by
-default. Liquid templates support locals and objects that respond to
-`#to_h` as scopes:
-
-    >> require 'liquid'
-    >> require 'tilt'
-    >> template = Tilt.new('hello.liquid')
-    => #<Tilt::LiquidTemplate @file='hello.liquid'>
-    >> scope = { :title => "Hello Liquid Templates" }
-    >> template.render(nil, :world => "Liquid")
-    => "
-    <html>
-      <head>
-        <title>Hello Liquid Templates</title>
-      </head>
-      <body>
-        <h1>Hello Liquid!</h1>
-      </body>
-    </html>"
-
-Or, use `Tilt::LiquidTemplate` directly to process strings:
-
-    >> require 'liquid'
-    >> template = Tilt::LiquidTemplate.new { "<h1>Hello Liquid!</h1>" }
-    => #<Tilt::LiquidTemplate @file=nil ...>
-    >> template.render
-    => "<h1>Hello Liquid!</h1>"
-
-__NOTE:__ It's suggested that your program `require 'liquid'` at load
-time when using this template engine within a threaded environment.
-
-### See also
-
-  * [Liquid for Programmers](https://wiki.github.com/Shopify/liquid/liquid-for-programmers)
-  * [Liquid Docs](http://liquid.rubyforge.org/)
-  * GitHub: [Shopify/liquid](https://github.com/Shopify/liquid/)
-
-
-<a name='radius'></a>
-Radius (`radius`)
------------------
-
-[Radius][radius] is the template language used by [Radiant CMS][radiant]. It is
-a tag language designed to be valid XML/HTML.
-
-### Example
-
-    <html>
-    <body>
-      <h1><r:title /></h1>
-      <ul class="<r:type />">
-      <r:repeat times="3">
-        <li><r:hello />!</li>
-      </r:repeat>
-      </ul>
-      <r:yield />
-    </body>
-    </html>
-
-### Usage
-
-To render a template such as the one above.
-
-    scope = OpenStruct.new
-    scope.title = "Radius Example"
-    scope.hello = "Hello, World!"
-
-    require 'radius'
-    template = Tilt::RadiusTemplate.new('example.radius', :tag_prefix=>'r')
-    template.render(scope, :type=>'hlist'){ "Jackpot!" }
-
-The result will be:
-
-    <html>
-    <body>
-      <h1>Radius Example</h1>
-      <ul class="hlist">
-        <li>Hello, World!</li>
-        <li>Hello, World!</li>
-        <li>Hello, World!</li>
-      </ul>
-      Jackpot!
-    </body>
-    </html>
-
-### See also
-
-  * [Radius][radius]
-  * [Radiant CMS][radiant]
-
-
-<a name='textile'></a>
-Textile (`textile`)
--------------------
-
-Textile is a lightweight markup language originally developed by Dean Allen and
-billed as a "humane Web text generator". Textile converts its marked-up text
-input to valid, well-formed XHTML and also inserts character entity references
-for apostrophes, opening and closing single and double quotation marks,
-ellipses and em dashes.
-
-Textile formatted texts are converted to HTML with the [RedCloth][redcloth]
-engine, which is a Ruby extension written in C.
-
-### Example
-
-    h1. Hello Textile Templates
-
-    Hello World. This is a paragraph.
-
-### Usage
-
-__NOTE:__ It's suggested that your program `require 'redcloth'` at load time
-when using this template engine in a threaded environment.
-
-### See Also
-
-  * [RedCloth][redcloth]
-
-<a name='rst'></a>
-reStructuredText (`rst`)
--------------------
-
-reStructuredText is a lightweight markup language originally developed by David Goodger,
-based on StructuredText and Setext. reStructuredText is primarily used for technical
-documentation in the Python programming language community, e.g. by the
-[Sphinx](http://www.sphinx-doc.org/en/stable/rest.html) Python documentation generator.
-
-reStructuredText formatted texts are converted to HTML with [Pandoc][pandoc], which
-is an application written in Haskell, with a Ruby wrapper provided by the
-[pandoc-ruby][pandoc-ruby] gem.
-
-### Example
-
-    Hello Rst Templates
-    ===================
-
-    Hello World. This is a paragraph.
-
-### See Also
-
-  * [Pandoc][pandoc]
-  * [pandoc-ruby][pandoc-ruby]
-
-
-<a name='rdoc'></a>
-RDoc (`rdoc`)
--------------
-
-[RDoc][rdoc] is the simple text markup system that comes with Ruby's standard
-library.
-
-### Example
-
-    = Hello RDoc Templates
-
-    Hello World. This is a paragraph.
-
-### Usage
-
-__NOTE:__ It's suggested that your program `require 'rdoc'`,
-`require 'rdoc/markup'`, and `require 'rdoc/markup/to_html'` at load time
-when using this template engine in a threaded environment.
-
-### See also
-
- * [RDoc][rdoc]
-
-
-<a name='markdown'></a>
-Markdown (`markdown`, `md`, `mkd`)
-----------------------------------
-
-[Markdown][markdown] is a lightweight markup language, created by John Gruber
-and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML
-is used.  Marking up plain text with Markdown markup is easy and Markdown
-formatted texts are readable.
-
-Markdown formatted texts are converted to HTML with one of these libraries:
-
-  * [RDiscount](#rdiscount) - `Tilt::RDiscountTemplate`
-  * Redcarpet - `Tilt::RedcarpetTemplate`
-  * Kramdown - `Tilt::KramdownTemplate`
-  * Pandoc - `Tilt::PandocTemplate`
-  * CommonMarker - `Tilt::CommonMarkerTemplate`
-
-### Example
-
-    Hello Markdown Templates
-    ========================
-
-    Hello World. This is a paragraph.
-
-### Usage
-
-To wrap a Markdown formatted document with a layout:
-
-    layout = Tilt['erb'].new do
-      "<!doctype html><title></title><%= yield %>"
-    end
-    data = Tilt['md'].new { "# hello tilt" }
-    layout.render { data.render }
-    # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
-
-### Options
-
-Every implementation of Markdown *should* support these options, but there are
-some known problems with the Kramdown engine.
-
-#### `:smartypants => true|false`
-
-Set `true` to enable [Smarty Pants][smartypants] style punctuation replacement.
-
-In Kramdown this option only applies to smart quotes. It will apply a
-subset of Smarty Pants (e.g. `...` to `…`) regardless of any option.
-
-#### `:escape_html => true|false`
-
-Set `true` disallow raw HTML in Markdown contents. HTML is converted to
-literal text by escaping `<` characters.
-
-Kramdown doesn't support this option.
-
-### See also
-
- * [Markdown Syntax Documentation](http://daringfireball.net/projects/markdown/syntax)
-
-<a name='rdiscount'></a>
-RDiscount (`markdown`, `md`, `mkd`)
------------------------------------
-
-[Discount][discount] is an implementation of the Markdown markup language in C.
-[RDiscount][rdiscount] is a Ruby wrapper around Discount.
-
-All the documentation of [Markdown](#markdown) applies in addition to the following:
-
-### Usage
-
-The `Tilt::RDiscountTemplate` class is registered for all files ending in
-`.markdown`, `.md` or `.mkd` by default with the highest priority. If you
-specifically want to use RDiscount, it's recommended to use `#prefer`:
-
-    Tilt.prefer Tilt::RDiscountTemplate
-
-__NOTE:__ It's suggested that your program `require 'rdiscount'` at load time when
-using this template engine within a threaded environment.
-
-### See also
-
-  * [Discount][discount]
-  * [RDiscount][rdiscount]
-  * GitHub: [rtomayko/rdiscount][rdiscount]
-
-
-[sass]: http://sass-lang.com/ "Sass"
-[coffee-script]: http://jashkenas.github.com/coffee-script/ "Coffee Script"
-[erubi]: https://github.com/jeremyevans/erubi "Erubi"
-[haml]: http://haml.info/ "Haml"
-[liquid]: http://www.liquidmarkup.org/ "Liquid"
-[radius]: http://radius.rubyforge.org/ "Radius"
-[radiant]: http://radiantcms.org/ "Radiant CMS"
-[redcloth]: http://redcloth.org/ "RedCloth"
-[rdoc]: http://rdoc.rubyforge.org/ "RDoc"
-[discount]: http://www.pell.portland.or.us/~orc/Code/discount/ "Discount"
-[rdiscount]: http://github.com/rtomayko/rdiscount/ "RDiscount"
-[smartypants]: http://daringfireball.net/projects/smartypants/ "Smarty Pants"
-[markdown]: http://en.wikipedia.org/wiki/Markdown "Markdown"
-[pandoc]: http://pandoc.org/ "Pandoc"
-[pandoc-ruby]: https://github.com/alphabetum/pandoc-ruby "pandoc-ruby"
diff --git a/lib/tilt/asciidoc.rb b/lib/tilt/asciidoc.rb
index 0684ae0..2c0c857 100644
--- a/lib/tilt/asciidoc.rb
+++ b/lib/tilt/asciidoc.rb
@@ -1,14 +1,21 @@
 # frozen_string_literal: true
-require_relative 'template'
-require 'asciidoctor'
-# AsciiDoc see: http://asciidoc.org/
 
-# Asciidoctor implementation for AsciiDoc see:
-# http://asciidoctor.github.com/
+# = AsciiDoc
+#
+# Asciidoctor implementation for AsciiDoc
 #
 # Asciidoctor is an open source, pure-Ruby processor for
 # converting AsciiDoc documents or strings into HTML 5,
 # DocBook 4.5 and other formats.
+#
+# === See also
+#
+# * http://asciidoc.org
+# * http://asciidoctor.github.com
+
+require_relative 'template'
+require 'asciidoctor'
+
 Tilt::AsciidoctorTemplate = Tilt::StaticTemplate.subclass do
   @options[:header_footer] = false if @options[:header_footer].nil?
   Asciidoctor.render(@data, @options)
diff --git a/lib/tilt/babel.rb b/lib/tilt/babel.rb
index d1e749d..493b2b6 100644
--- a/lib/tilt/babel.rb
+++ b/lib/tilt/babel.rb
@@ -1,4 +1,9 @@
 # frozen_string_literal: true
+
+# = Babel
+#
+#
+
 require_relative 'template'
 require 'babel/transpiler'
 
diff --git a/lib/tilt/builder.rb b/lib/tilt/builder.rb
index 6349a6c..e5472dc 100644
--- a/lib/tilt/builder.rb
+++ b/lib/tilt/builder.rb
@@ -1,4 +1,8 @@
 # frozen_string_literal: true
+
+# = Builder
+#
+
 require_relative 'template'
 require 'builder'
 
diff --git a/lib/tilt/coffee.rb b/lib/tilt/coffee.rb
index 95dfbd2..47eb3bd 100644
--- a/lib/tilt/coffee.rb
+++ b/lib/tilt/coffee.rb
@@ -1,12 +1,21 @@
 # frozen_string_literal: true
+
+# CoffeeScript template implementation.
+#
+# CoffeeScript templates do not support object scopes, locals, or yield.
+#
+# === See also
+#
+# * http://coffeescript.org
+#
+# === Related module
+#
+# * Tilt::CoffeeScriptTemplate
+
 require_relative 'template'
 require 'coffee_script'
 
 module Tilt
-  # CoffeeScript template implementation. See:
-  # http://coffeescript.org/
-  #
-  # CoffeeScript templates do not support object scopes, locals, or yield.
   class CoffeeScriptTemplate < StaticTemplate
     self.default_mime_type = 'application/javascript'
 
diff --git a/lib/tilt/commonmarker.rb b/lib/tilt/commonmarker.rb
index d55acd1..5bb16a2 100644
--- a/lib/tilt/commonmarker.rb
+++ b/lib/tilt/commonmarker.rb
@@ -1,4 +1,45 @@
 # frozen_string_literal: true
+#
+# = Markdown (<tt>markdown</tt>, <tt>md</tt>, <tt>mkd</tt>)
+#
+# Markdown is a lightweight markup language, created by John Gruber
+# and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML
+# is used.  Marking up plain text with Markdown markup is easy and Markdown
+# formatted texts are readable.
+#
+# === Example
+#
+#     Hello Markdown Templates
+#     ========================
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# To wrap a Markdown formatted document with a layout:
+#
+#     layout = Tilt['erb'].new do
+#       "<!doctype html><title></title><%= yield %>"
+#     end
+#     data = Tilt['md'].new { "# hello tilt" }
+#     layout.render { data.render }
+#     # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
+#
+# === Options
+#
+# ==== <tt>:smartypants => true|false</tt>
+#
+# Set <tt>true</tt> to enable [Smarty Pants][smartypants] style punctuation replacement.
+#
+# ==== <tt>:escape_html => true|false</tt>
+#
+# Set <tt>true</tt> disallow raw HTML in Markdown contents. HTML is converted to
+# literal text by escaping <tt><</tt> characters.
+#
+# === See also
+#
+# * {Markdown Syntax Documentation}[http://daringfireball.net/projects/markdown/syntax]
+
 require_relative 'template'
 require 'commonmarker'
 
diff --git a/lib/tilt/creole.rb b/lib/tilt/creole.rb
index 4e40aa9..910fe12 100644
--- a/lib/tilt/creole.rb
+++ b/lib/tilt/creole.rb
@@ -1,4 +1,13 @@
 # frozen_string_literal: true
+
+# = Creole
+#
+# Creole implementation
+#
+# === See also
+#
+# * http://www.wikicreole.org/
+
 require_relative 'template'
 require 'creole'
 
@@ -6,7 +15,6 @@
 
 allowed_opts = [:allowed_schemes, :extensions, :no_escape].freeze
 
-# Creole implementation. See: http://www.wikicreole.org/
 Tilt::CreoleTemplate = Tilt::StaticTemplate.subclass do
   opts = {}
   allowed_opts.each do |k|
diff --git a/lib/tilt/csv.rb b/lib/tilt/csv.rb
index 2a9c3e7..3e449c7 100644
--- a/lib/tilt/csv.rb
+++ b/lib/tilt/csv.rb
@@ -1,34 +1,44 @@
 # frozen_string_literal: true
+
+# = CSV
+#
+# CSV Template implementation.
+#
+# === Example
+#
+#    # Example of csv template
+#    tpl = <<-EOS
+#      # header
+#      csv << ['NAME', 'ID']
+#
+#      # data rows
+#      @people.each do |person|
+#        csv << [person[:name], person[:id]]
+#      end
+#    EOS
+#
+#    @people = [
+#      {:name => "Joshua Peek", :id => 1},
+#      {:name => "Ryan Tomayko", :id => 2},
+#      {:name => "Simone Carletti", :id => 3}
+#    ]
+#
+#    template = Tilt::CSVTemplate.new { tpl }
+#    template.render(self)
+#
+# === See also
+#
+# * http://ruby-doc.org/stdlib/libdoc/csv/rdoc/CSV.html
+#
+# === Related module
+#
+# * Tilt::CSVTemplate
+
 require_relative 'template'
 require 'csv'
 
 module Tilt
 
-  # CSV Template implementation. See:
-  # http://ruby-doc.org/stdlib/libdoc/csv/rdoc/CSV.html
-  #
-  # == Example
-  #
-  #    # Example of csv template
-  #    tpl = <<-EOS
-  #      # header
-  #      csv << ['NAME', 'ID']
-  #
-  #      # data rows
-  #      @people.each do |person|
-  #        csv << [person[:name], person[:id]]
-  #      end
-  #    EOS
-  #
-  #    @people = [
-  #      {:name => "Joshua Peek", :id => 1},
-  #      {:name => "Ryan Tomayko", :id => 2},
-  #      {:name => "Simone Carletti", :id => 3}
-  #    ]
-  #
-  #    template = Tilt::CSVTemplate.new { tpl }
-  #    template.render(self)
-  #
   class CSVTemplate < Template
     self.default_mime_type = 'text/csv'
 
diff --git a/lib/tilt/erb.rb b/lib/tilt/erb.rb
index a250c69..8a1b3c6 100644
--- a/lib/tilt/erb.rb
+++ b/lib/tilt/erb.rb
@@ -1,10 +1,75 @@
 # frozen_string_literal: true
+
+# = ERB (<tt>erb</tt>, <tt>rhtml</tt>)
+#
+# ERB is a simple but powerful template languge for Ruby. In Tilt it's
+# backed by {Erubi}[rdoc-ref:lib/tilt/erubi.rb] (if installed on your system] or by
+# {erb.rb}[rdoc-ref:lib/tilt/erb.rb] (which is included in Ruby's standard library]. This
+# documentation applies to all three implementations.
+#
+# === Example
+#
+#     Hello <%= world %>!
+#
+# === Usage
+#
+# ERB templates support custom evaluation scopes and locals:
+#
+#     >> require 'erb'
+#     >> template = Tilt.new('hello.html.erb')
+#     >> template.render(self, :world => 'World!')
+#     => "Hello World!"
+#
+# Or, use <tt>Tilt['erb']</tt> directly to process strings:
+#
+#     template = Tilt['erb'].new { "Hello <%= world %>!" }
+#     template.render(self, :world => 'World!')
+#
+# The <tt>Tilt::ERBTemplate</tt> class is registered for all files ending in <tt>.erb</tt> or
+# <tt>.rhtml</tt> by default, but with a *lower* priority than ErubiTemplate.
+# If you specifically want to use ERB, it's recommended to use
+# <tt>#prefer</tt>:
+#
+#     Tilt.prefer Tilt::ERBTemplate
+#
+# __NOTE:__ It's suggested that your program <tt>require 'erb'</tt> at load time when
+# using this template engine within a threaded environment.
+#
+# === Options
+#
+# ==== <tt>:trim => trim</tt>
+#
+# The ERB trim mode flags. This is a string consisting of any combination of the
+# following characters:
+#
+# * <tt>'>'</tt>  omits newlines for lines ending in <tt>></tt>
+# * <tt>'<>'</tt> omits newlines for lines starting with <tt><%</tt> and ending in <tt>%></tt>
+# * <tt>'%'</tt>  enables processing of lines beginning with <tt>%</tt>
+# * <tt>true</tt> is an alias of <tt><></tt>
+#
+# ==== <tt>:outvar => '_erbout'</tt>
+#
+# The name of the variable used to accumulate template output. This can be
+# any valid Ruby expression but must be assignable. By default a local
+# variable named <tt>_erbout</tt> is used.
+#
+# ==== <tt>:freeze => false</tt>
+#
+# If set to true, will set the <tt>frozen_string_literal</tt> flag in the compiled
+# template code, so that string literals inside the templates will be frozen.
+#
+# === See also
+#
+# * http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html
+#
+# === Related module
+#
+# * Tilt::ERBTemplate
+
 require_relative 'template'
 require 'erb'
 
 module Tilt
-  # ERB template implementation. See:
-  # http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html
   class ERBTemplate < Template
     SUPPORTS_KVARGS = ::ERB.instance_method(:initialize).parameters.assoc(:key) rescue false
 
diff --git a/lib/tilt/erubi.rb b/lib/tilt/erubi.rb
index 34d7883..c6bb49f 100644
--- a/lib/tilt/erubi.rb
+++ b/lib/tilt/erubi.rb
@@ -1,16 +1,49 @@
 # frozen_string_literal: true
+
+# = Erubi (<tt>erb</tt>, <tt>rhtml</tt>, <tt>erubi</tt>)
+#
+# {Erubi}[https://github.com/jeremyevans/erubi] is an ERB implementation that uses the same algorithm as
+# the erubis gem, but is maintained and offers numerous improvements.
+#
+# All the documentation of {ERB}[rdoc-ref:lib/tilt/erb.rb] applies in addition to the following:
+#
+# === Usage
+#
+# The <tt>Tilt::ErubiTemplate</tt> class is registered for all files ending in <tt>.erb</tt> or
+# <tt>.rhtml</tt> by default, with the *highest* priority.
+#
+# __NOTE:__ It's suggested that your program <tt>require 'erubi'</tt> at load time when
+# using this template engine within a threaded environment.
+#
+# === Options
+#
+# ==== <tt>:engine_class => Erubi::Engine</tt>
+#
+# Allows you to specify a custom engine class to use instead of the
+# default which is <tt>Erubi::Engine</tt>.
+#
+# ==== Other
+#
+# Other options are passed to the constructor of the engine class.
+#
+# ErubiTemplate supports the following additional options, in addition
+# to the options supported by the Erubi engine:
+#
+# :engine_class :: allows you to specify a custom engine class to use
+#                  instead of the default (which is ::Erubi::Engine).
+#
+# === See also
+#
+# * {Erubi Home}[https://github.com/jeremyevans/erubi]
+#
+# === Related module
+#
+# * Tilt::ErubiTemplate
+
 require_relative 'template'
 require 'erubi'
 
 module Tilt
-  # Erubi (a simplified version of Erubis) template implementation.
-  # See https://github.com/jeremyevans/erubi
-  #
-  # ErubiTemplate supports the following additional options, in addition
-  # to the options supported by the Erubi engine:
-  #
-  # :engine_class :: allows you to specify a custom engine class to use
-  #                  instead of the default (which is ::Erubi::Engine).
   class ErubiTemplate < Template
     def prepare
       @options[:preamble] = false
diff --git a/lib/tilt/etanni.rb b/lib/tilt/etanni.rb
index 7d273d8..7d84c2c 100644
--- a/lib/tilt/etanni.rb
+++ b/lib/tilt/etanni.rb
@@ -1,4 +1,11 @@
 # frozen_string_literal: true
+
+# = Etanni
+#
+# === Related module
+#
+# * Tilt::EtanniTemplate
+
 require_relative 'template'
 
 module Tilt
diff --git a/lib/tilt/haml.rb b/lib/tilt/haml.rb
index 3751a31..ff29b3e 100644
--- a/lib/tilt/haml.rb
+++ b/lib/tilt/haml.rb
@@ -1,4 +1,70 @@
 # frozen_string_literal: true
+
+# = Haml (<tt>haml</tt>)
+#
+# {Haml}[https://haml.info] is a markup language that’s used to cleanly and simply describe
+# the HTML of any web document without the use of inline code. Haml functions as
+# a replacement for inline page templating systems such as PHP, ASP, and ERB, the
+# templating language used in most Ruby on Rails applications. However, Haml
+# avoids the need for explicitly coding HTML into the template, because it itself
+# is a description of the HTML, with some code to generate dynamic content.
+# ({more}[http://haml.info/about.html)]
+#
+# === Example
+#
+#     %html
+#       %head
+#         %title= @title
+#       %body
+#         %h1
+#           Hello
+#           = world + '!'
+#
+# === Usage
+#
+# The <tt>Tilt::HamlTemplate</tt> class is registered for all files ending in <tt>.haml</tt>
+# by default. Haml templates support custom evaluation scopes and locals:
+#
+#     >> require 'haml'
+#     >> template = Tilt.new('hello.haml')
+#     => #<Tilt::HamlTemplate @file='hello.haml'>
+#     >> @title = "Hello Haml!"
+#     >> template.render(self, :world => 'Haml!')
+#     => "
+#     <html>
+#       <head>
+#         <title>Hello Haml!</title>
+#       </head>
+#       <body>
+#         <h1>Hello Haml!</h1>
+#       </body>
+#     </html>"
+#
+# Or, use the <tt>Tilt::HamlTemplate</tt> class directly to process strings:
+#
+#     >> require 'haml'
+#     >> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
+#     => #<Tilt::HamlTemplate @file=nil ...>
+#     >> template.render
+#     => "<h1>Hello Haml!</h1>"
+#
+# __NOTE:__ It's suggested that your program <tt>require 'haml'</tt> at load time when
+# using this template engine within a threaded environment.
+#
+# === Options
+#
+# Please see the {Haml Reference}[http://haml.info/docs/yardoc/file.HAML_REFERENCE.html#options] for all available options.
+#
+# === See also
+#
+# * {#haml.docs}[http://haml.info/docs.html]
+# * {Haml Tutorial}[http://haml.info/tutorial.html]
+# * {Haml Reference}[http://haml.info/docs/yardoc/file.HAML_REFERENCE.html]
+#
+# === Related module
+#
+# * Tilt::HamlTemplate
+
 require_relative 'template'
 require 'haml'
 
@@ -12,7 +78,7 @@ module Tilt
     class HamlTemplate < Template
       self.default_mime_type = 'text/html'
 
-      # `Gem::Version.correct?` may return false because of Haml::VERSION #=> "3.1.8 (Separated Sally)". After Haml 4, it's always correct.
+      # <tt>Gem::Version.correct?</tt> may return false because of Haml::VERSION #=> "3.1.8 (Separated Sally)". After Haml 4, it's always correct.
       if Gem::Version.correct?(Haml::VERSION) && Gem::Version.new(Haml::VERSION) >= Gem::Version.new('5.0.0.beta.2')
         def prepare
           @options[:filename] = eval_file
diff --git a/lib/tilt/kramdown.rb b/lib/tilt/kramdown.rb
index df0aeaf..b774ca9 100644
--- a/lib/tilt/kramdown.rb
+++ b/lib/tilt/kramdown.rb
@@ -1,10 +1,56 @@
 # frozen_string_literal: true
+
+# = Markdown (<tt>markdown</tt>, <tt>md</tt>, <tt>mkd</tt>)
+#
+# Markdown is a lightweight markup language, created by John Gruber
+# and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML
+# is used.  Marking up plain text with Markdown markup is easy and Markdown
+# formatted texts are readable.
+#
+# === Example
+#
+#     Hello Markdown Templates
+#     ========================
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# To wrap a Markdown formatted document with a layout:
+#
+#     layout = Tilt['erb'].new do
+#       "<!doctype html><title></title><%= yield %>"
+#     end
+#     data = Tilt['md'].new { "# hello tilt" }
+#     layout.render { data.render }
+#     # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
+#
+# === Options
+#
+# Every implementation of Markdown *should* support these options, but there are
+# some known problems with the Kramdown engine.
+#
+# ==== <tt>:smartypants => true|false</tt>
+#
+# Set <tt>true</tt> to enable [Smarty Pants][smartypants] style punctuation replacement.
+#
+# In Kramdown this option only applies to smart quotes. It will apply a
+# subset of Smarty Pants (e.g. <tt>...</tt> to <tt>…</tt>) regardless of any option.
+#
+# ==== <tt>:escape_html => true|false</tt>
+#
+# Kramdown doesn't support this option.
+#
+# === See also
+#
+# * {Markdown Syntax Documentation}[http://daringfireball.net/projects/markdown/syntax]
+# * {Kramdown Markdown implementation}[https://kramdown.gettalong.org]
+
 require_relative 'template'
 require 'kramdown'
 
 dumb_quotes = [39, 39, 34, 34].freeze
 
-# Kramdown Markdown implementation. See: https://kramdown.gettalong.org/
 Tilt::KramdownTemplate = Tilt::StaticTemplate.subclass do
   # dup as Krawmdown modifies the passed option with map!
   @options[:smart_quotes] = dumb_quotes.dup unless @options[:smartypants]
diff --git a/lib/tilt/liquid.rb b/lib/tilt/liquid.rb
index fe65d04..d20e330 100644
--- a/lib/tilt/liquid.rb
+++ b/lib/tilt/liquid.rb
@@ -1,18 +1,74 @@
 # frozen_string_literal: true
+
+# = Liquid (<tt>liquid</tt>)
+#
+# Liquid is designed to be a *safe* template system and therefore
+# does not provide direct access to execuatable scopes. In order to
+# support a +scope+, the +scope+ must be able to represent itself
+# as a hash by responding to #to_h. If the +scope+ does not respond
+# to #to_h it will be ignored.
+#
+# LiquidTemplate does not support yield blocks.
+#
+# === Example
+#
+#     <html>
+#       <head>
+#         <title>{{ title }}</title>
+#       </head>
+#       <body>
+#         <h1>Hello {{ world }}!</h1>
+#       </body>
+#     </html>
+#
+# === Usage
+#
+# <tt>Tilt::LiquidTemplate</tt> is registered for all files ending in <tt>.liquid</tt> by
+# default. Liquid templates support locals and objects that respond to
+# <tt>#to_h</tt> as scopes:
+#
+#     >> require 'liquid'
+#     >> require 'tilt'
+#     >> template = Tilt.new('hello.liquid')
+#     => #<Tilt::LiquidTemplate @file='hello.liquid'>
+#     >> scope = { :title => "Hello Liquid Templates" }
+#     >> template.render(nil, :world => "Liquid")
+#     => "
+#     <html>
+#       <head>
+#         <title>Hello Liquid Templates</title>
+#       </head>
+#       <body>
+#         <h1>Hello Liquid!</h1>
+#       </body>
+#     </html>"
+#
+# Or, use <tt>Tilt::LiquidTemplate</tt> directly to process strings:
+#
+#     >> require 'liquid'
+#     >> template = Tilt::LiquidTemplate.new { "<h1>Hello Liquid!</h1>" }
+#     => #<Tilt::LiquidTemplate @file=nil ...>
+#     >> template.render
+#     => "<h1>Hello Liquid!</h1>"
+#
+# __NOTE:__ It's suggested that your program <tt>require 'liquid'</tt> at load
+# time when using this template engine within a threaded environment.
+#
+# === See also
+#
+# * {Liquid}[http://liquidmarkup.org]
+# * {Liquid for Programmers}[https://wiki.github.com/Shopify/liquid/liquid-for-programmers]
+# * {Liquid Docs}[http://liquid.rubyforge.org/]
+# * GitHub: {Shopify/liquid}[https://github.com/Shopify/liquid/]
+#
+# === Related module
+#
+# * Tilt::LiquidTemplate
+
 require_relative 'template'
 require 'liquid'
 
 module Tilt
-  # Liquid template implementation. See:
-  # http://liquidmarkup.org/
-  #
-  # Liquid is designed to be a *safe* template system and therefore
-  # does not provide direct access to execuatable scopes. In order to
-  # support a +scope+, the +scope+ must be able to represent itself
-  # as a hash by responding to #to_h. If the +scope+ does not respond
-  # to #to_h it will be ignored.
-  #
-  # LiquidTemplate does not support yield blocks.
   class LiquidTemplate < Template
     def prepare
       @options[:line_numbers] = true unless @options.has_key?(:line_numbers)
diff --git a/lib/tilt/livescript.rb b/lib/tilt/livescript.rb
index ab975f9..3b50d8c 100644
--- a/lib/tilt/livescript.rb
+++ b/lib/tilt/livescript.rb
@@ -1,11 +1,18 @@
 # frozen_string_literal: true
-require_relative 'template'
-require 'livescript'
 
-# LiveScript template implementation. See:
-# http://livescript.net/
+# = LiveScript
+#
+# LiveScript template implementation.
 #
 # LiveScript templates do not support object scopes, locals, or yield.
+#
+# === See also
+#
+# * http://livescript.net
+
+require_relative 'template'
+require 'livescript'
+
 Tilt::LiveScriptTemplate = Tilt::StaticTemplate.subclass(mime_type: 'application/javascript') do
   LiveScript.compile(@data, @options)
 end
diff --git a/lib/tilt/mapping.rb b/lib/tilt/mapping.rb
index a4cb3b3..1ade23d 100644
--- a/lib/tilt/mapping.rb
+++ b/lib/tilt/mapping.rb
@@ -119,8 +119,8 @@ def split(file)
   #     # => RDiscount::Template
   #
   # In the previous example we say that RDiscount has a *higher priority* than
-  # Kramdown. Tilt will first try to `require "rdiscount/template"`, falling
-  # back to `require "kramdown/template"`. If none of these are successful,
+  # Kramdown. Tilt will first try to <tt>require "rdiscount/template"</tt>, falling
+  # back to <tt>require "kramdown/template"</tt>. If none of these are successful,
   # the first error will be raised.
   class Mapping < BaseMapping
     LOCK = Mutex.new
@@ -346,13 +346,13 @@ def lazy_load(pattern)
     end
 
     # The proper behavior (in MRI) for autoload? is to
-    # return `false` when the constant/file has been
+    # return <tt>false</tt> when the constant/file has been
     # explicitly required.
     #
-    # However, in JRuby it returns `true` even after it's
-    # been required. In that case it turns out that `defined?`
-    # returns `"constant"` if it exists and `nil` when it doesn't.
-    # This is actually a second bug: `defined?` should resolve
+    # However, in JRuby it returns <tt>true</tt> even after it's
+    # been required. In that case it turns out that <tt>defined?</tt>
+    # returns <tt>"constant"</tt> if it exists and <tt>nil</tt> when it doesn't.
+    # This is actually a second bug: <tt>defined?</tt> should resolve
     # autoload (aka. actually try to require the file).
     #
     # We use the second bug in order to resolve the first bug.
diff --git a/lib/tilt/markaby.rb b/lib/tilt/markaby.rb
index 5dbdd45..a38b12a 100644
--- a/lib/tilt/markaby.rb
+++ b/lib/tilt/markaby.rb
@@ -1,10 +1,19 @@
 # frozen_string_literal: true
+
+# = Markaby
+#
+# === See also
+#
+# * http://github.com/markaby/markaby
+#
+# === Related module
+#
+# * Tilt::MarkabyTemplate
+
 require_relative 'template'
 require 'markaby'
 
 module Tilt
-  # Markaby
-  # http://github.com/markaby/markaby
   class MarkabyTemplate < Template
     def self.builder_class
       @builder_class ||= Class.new(Markaby::Builder) do
diff --git a/lib/tilt/nokogiri.rb b/lib/tilt/nokogiri.rb
index fac92bb..6bd8e28 100644
--- a/lib/tilt/nokogiri.rb
+++ b/lib/tilt/nokogiri.rb
@@ -1,10 +1,21 @@
 # frozen_string_literal: true
+
+# = Nokogiri
+#
+# Nokogiri template implementation.
+#
+# === See also
+#
+# * http://nokogiri.org/
+#
+# === Related module
+#
+# * Tilt::NokogiriTemplate
+
 require_relative 'template'
 require 'nokogiri'
 
 module Tilt
-  # Nokogiri template implementation. See:
-  # http://nokogiri.org/
   class NokogiriTemplate < Template
     DOCUMENT_HEADER = /\A<\?xml version=\"1\.0\"\?>\n?/
     self.default_mime_type = 'text/xml'
diff --git a/lib/tilt/pandoc.rb b/lib/tilt/pandoc.rb
index 4572a8e..ec1f574 100644
--- a/lib/tilt/pandoc.rb
+++ b/lib/tilt/pandoc.rb
@@ -1,8 +1,50 @@
 # frozen_string_literal: true
+
+# = Markdown (<tt>markdown</tt>, <tt>md</tt>, <tt>mkd</tt>)
+#
+# {Markdown}[http://daringfireball.net/projects/markdown/syntax] is a
+# lightweight markup language, created by John Gruber and Aaron Swartz.
+# For any markup that is not covered by Markdown’s syntax, HTML is used.
+# Marking up plain text with Markdown markup is easy and Markdown
+# formatted texts are readable.
+#
+# === Example
+#
+#     Hello Markdown Templates
+#     ========================
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# To wrap a Markdown formatted document with a layout:
+#
+#     layout = Tilt['erb'].new do
+#       "<!doctype html><title></title><%= yield %>"
+#     end
+#     data = Tilt['md'].new { "# hello tilt" }
+#     layout.render { data.render }
+#     # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
+#
+# === Options
+#
+# ==== <tt>:smartypants => true|false</tt>
+#
+# Set <tt>true</tt> to enable [Smarty Pants][smartypants] style punctuation replacement.
+#
+# ==== <tt>:escape_html => true|false</tt>
+#
+# Set <tt>true</tt> disallow raw HTML in Markdown contents. HTML is converted to
+# literal text by escaping <tt><</tt> characters.
+#
+# === See also
+#
+# * {Markdown Syntax Documentation}[http://daringfireball.net/projects/markdown/syntax]
+# * {Pandoc}[http://pandoc.org]
+
 require_relative 'template'
 require 'pandoc-ruby'
 
-# Pandoc markdown implementation. See: http://pandoc.org/
 Tilt::PandocTemplate = Tilt::StaticTemplate.subclass do
   # turn options hash into an array
   # Map tilt options to pandoc options
diff --git a/lib/tilt/pipeline.rb b/lib/tilt/pipeline.rb
index 6d6621f..46fe8d9 100644
--- a/lib/tilt/pipeline.rb
+++ b/lib/tilt/pipeline.rb
@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative 'template'
 
 module Tilt
diff --git a/lib/tilt/plain.rb b/lib/tilt/plain.rb
index 6414b10..a7e1e8e 100644
--- a/lib/tilt/plain.rb
+++ b/lib/tilt/plain.rb
@@ -1,5 +1,9 @@
 # frozen_string_literal: true
-require_relative 'template'
 
+# = Plain
+#
 # Raw text (no template functionality).
+
+require_relative 'template'
+
 Tilt::PlainTemplate = Tilt::StaticTemplate.subclass{@data}
diff --git a/lib/tilt/prawn.rb b/lib/tilt/prawn.rb
index 35ad8a3..6fba5a1 100644
--- a/lib/tilt/prawn.rb
+++ b/lib/tilt/prawn.rb
@@ -1,18 +1,30 @@
 # frozen_string_literal: true
+
+# = Prawn
+#
+# Prawn template implementation.
+#
+# === See also
+#
+# * http://prawnpdf.org
+#
+# === Related module
+#
+# * Tilt::PrawnTemplate
+
 require_relative 'template'
 require 'prawn'
 
 module Tilt
-  # Prawn template implementation. See: http://prawnpdf.org
   class PrawnTemplate < Template
     self.default_mime_type = 'application/pdf'
-    
+
     def prepare
       @options[:page_size] = 'A4' unless @options.has_key?(:page_size)
       @options[:page_layout] = :portrait unless @options.has_key?(:page_layout)
       @engine = ::Prawn::Document.new(@options)
     end
-    
+
     def evaluate(scope, locals, &block)
       pdf = @engine
       locals = locals.dup
@@ -20,7 +32,7 @@ def evaluate(scope, locals, &block)
       super
       pdf.render
     end
-    
+
     def precompiled_template(locals)
       @data.to_str
     end
diff --git a/lib/tilt/radius.rb b/lib/tilt/radius.rb
index fb07d0e..56731ad 100644
--- a/lib/tilt/radius.rb
+++ b/lib/tilt/radius.rb
@@ -1,4 +1,59 @@
 # frozen_string_literal: true
+
+# = Radius (<tt>radius</tt>)
+#
+# {Radius}[http://radius.rubyforge.org] is the template language used by {Radiant CMS}[http://radiantcms.org]. It is
+# a tag language designed to be valid XML/HTML.
+#
+# === Example
+#
+#     <html>
+#     <body>
+#       <h1><r:title /></h1>
+#       <ul class="<r:type />">
+#       <r:repeat times="3">
+#         <li><r:hello />!</li>
+#       </r:repeat>
+#       </ul>
+#       <r:yield />
+#     </body>
+#     </html>
+#
+# === Usage
+#
+# To render a template such as the one above.
+#
+#     scope = OpenStruct.new
+#     scope.title = "Radius Example"
+#     scope.hello = "Hello, World!"
+#
+#     require 'radius'
+#     template = Tilt::RadiusTemplate.new('example.radius', :tag_prefix=>'r')
+#     template.render(scope, :type=>'hlist'){ "Jackpot!" }
+#
+# The result will be:
+#
+#     <html>
+#     <body>
+#       <h1>Radius Example</h1>
+#       <ul class="hlist">
+#         <li>Hello, World!</li>
+#         <li>Hello, World!</li>
+#         <li>Hello, World!</li>
+#       </ul>
+#       Jackpot!
+#     </body>
+#     </html>
+#
+# === See also
+#
+# * {Radius}[http://radius.rubyforge.org]
+# * {Radiant CMS}[http://radiantcms.org]
+#
+# === Related module
+#
+# * Tilt::RadiusTemplate
+
 require_relative 'template'
 require 'radius'
 
diff --git a/lib/tilt/rdiscount.rb b/lib/tilt/rdiscount.rb
index 5d59405..1959468 100644
--- a/lib/tilt/rdiscount.rb
+++ b/lib/tilt/rdiscount.rb
@@ -1,4 +1,69 @@
 # frozen_string_literal: true
+
+# = RDiscount (<tt>markdown</tt>, <tt>md</tt>, <tt>mkd</tt>)
+#
+# Markdown is a lightweight markup language, created by John Gruber
+# and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML
+# is used.  Marking up plain text with Markdown markup is easy and Markdown
+# formatted texts are readable.
+#
+# RDiscount is a simple text filter. It does not support +scope+ or
+# +locals+. The +:smart+ and +:filter_html+ options may be set true
+# to enable those flags on the underlying RDiscount object.
+#
+# === Example
+#
+#     Hello Markdown Templates
+#     ========================
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# To wrap a Markdown formatted document with a layout:
+#
+#     layout = Tilt['erb'].new do
+#       "<!doctype html><title></title><%= yield %>"
+#     end
+#     data = Tilt['md'].new { "# hello tilt" }
+#     layout.render { data.render }
+#     # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
+#
+# === Options
+#
+# ==== <tt>:smartypants => true|false</tt>
+#
+# Set <tt>true</tt> to enable [Smarty Pants][smartypants] style punctuation replacement.
+#
+# ==== <tt>:escape_html => true|false</tt>
+#
+# Set <tt>true</tt> disallow raw HTML in Markdown contents. HTML is converted to
+# literal text by escaping <tt><</tt> characters.
+#
+# === See also
+#
+#  * {Markdown Syntax Documentation}[http://daringfireball.net/projects/markdown/syntax]
+#  * [Discount][discount]
+#  * {RDiscount}[http://github.com/rtomayko/rdiscount]
+#
+# -----------------------------------
+#
+# [Discount][discount] is an implementation of the Markdown markup language in C.
+# [RDiscount][rdiscount] is a Ruby wrapper around Discount.
+#
+# All the documentation of {Markdown}[#markdown] applies in addition to the following:
+#
+# === Usage
+#
+# The <tt>Tilt::RDiscountTemplate</tt> class is registered for all files ending in
+# <tt>.markdown</tt>, <tt>.md</tt> or <tt>.mkd</tt> by default with the highest priority. If you
+# specifically want to use RDiscount, it's recommended to use <tt>#prefer</tt>:
+#
+#     Tilt.prefer Tilt::RDiscountTemplate
+#
+# __NOTE:__ It's suggested that your program <tt>require 'rdiscount'</tt> at load time when
+# using this template engine within a threaded environment.
+
 require_relative 'template'
 require 'rdiscount'
 
@@ -9,12 +74,6 @@
 
 _flags = [:smart, :filter_html, :smartypants, :escape_html].freeze
 
-# Discount Markdown implementation. See:
-# http://github.com/rtomayko/rdiscount
-#
-# RDiscount is a simple text filter. It does not support +scope+ or
-# +locals+. The +:smart+ and +:filter_html+ options may be set true
-# to enable those flags on the underlying RDiscount object.
 Tilt::RDiscountTemplate = Tilt::StaticTemplate.subclass do
   flags = _flags.select { |flag| @options[flag] }.
     map! { |flag| aliases[flag] || flag }
diff --git a/lib/tilt/rdoc.rb b/lib/tilt/rdoc.rb
index 8da6d11..2842eb4 100644
--- a/lib/tilt/rdoc.rb
+++ b/lib/tilt/rdoc.rb
@@ -1,11 +1,33 @@
 # frozen_string_literal: true
+
+# = RDoc (<tt>rdoc</tt>)
+#
+# {RDoc}[http://rdoc.rubyforge.org] is the simple text markup system that comes with Ruby's standard
+# library.
+#
+# === Example
+#
+#     = Hello RDoc Templates
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# __NOTE:__ It's suggested that your program <tt>require 'rdoc'</tt>,
+# <tt>require 'rdoc/markup'</tt>, and <tt>require 'rdoc/markup/to_html'</tt> at load time
+# when using this template engine in a threaded environment.
+#
+# === See also
+#
+# * {RDoc}[http://rdoc.rubyforge.org]
+# * {RDoc Github}[https://github.com/ruby/rdoc]
+
 require_relative 'template'
 require 'rdoc'
 require 'rdoc/markup'
 require 'rdoc/markup/to_html'
 require 'rdoc/options'
 
-# RDoc template. See: https://github.com/ruby/rdoc
 Tilt::RDocTemplate = Tilt::StaticTemplate.subclass do
   RDoc::Markup::ToHtml.new(RDoc::Options.new, nil).convert(@data).to_s
 end
diff --git a/lib/tilt/redcarpet.rb b/lib/tilt/redcarpet.rb
index ae82047..5e7ea8e 100644
--- a/lib/tilt/redcarpet.rb
+++ b/lib/tilt/redcarpet.rb
@@ -1,4 +1,46 @@
 # frozen_string_literal: true
+
+# = Markdown (<tt>markdown</tt>, <tt>md</tt>, <tt>mkd</tt>)
+#
+# {Markdown}[http://daringfireball.net/projects/markdown/syntax] is a
+# lightweight markup language, created by John Gruber and Aaron Swartz.
+# For any markup that is not covered by Markdown’s syntax, HTML is used.
+# Marking up plain text with Markdown markup is easy and Markdown
+# formatted texts are readable.
+#
+# === Example
+#
+#     Hello Markdown Templates
+#     ========================
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# To wrap a Markdown formatted document with a layout:
+#
+#     layout = Tilt['erb'].new do
+#       "<!doctype html><title></title><%= yield %>"
+#     end
+#     data = Tilt['md'].new { "# hello tilt" }
+#     layout.render { data.render }
+#     # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
+#
+# === Options
+#
+# ==== <tt>:smartypants => true|false</tt>
+#
+# Set <tt>true</tt> to enable [Smarty Pants][smartypants] style punctuation replacement.
+#
+# ==== <tt>:escape_html => true|false</tt>
+#
+# Set <tt>true</tt> disallow raw HTML in Markdown contents. HTML is converted to
+# literal text by escaping <tt><</tt> characters.
+#
+# === See also
+#
+# * {Markdown Syntax Documentation}[http://daringfireball.net/projects/markdown/syntax]
+
 require_relative 'template'
 require 'redcarpet'
 
diff --git a/lib/tilt/redcloth.rb b/lib/tilt/redcloth.rb
index 69e4156..a1376bb 100644
--- a/lib/tilt/redcloth.rb
+++ b/lib/tilt/redcloth.rb
@@ -1,8 +1,35 @@
 # frozen_string_literal: true
+
+# = Textile (<tt>textile</tt>)
+#
+# Textile is a lightweight markup language originally developed by Dean Allen and
+# billed as a "humane Web text generator". Textile converts its marked-up text
+# input to valid, well-formed XHTML and also inserts character entity references
+# for apostrophes, opening and closing single and double quotation marks,
+# ellipses and em dashes.
+#
+# Textile formatted texts are converted to HTML with the {RedCloth}[http://redcloth.org]
+# engine, which is a Ruby extension written in C.
+#
+# === Example
+#
+#     h1. Hello Textile Templates
+#
+#     Hello World. This is a paragraph.
+#
+# === Usage
+#
+# __NOTE:__ It's suggested that your program <tt>require 'redcloth'</tt> at load time
+# when using this template engine in a threaded environment.
+#
+# === See Also
+#
+# * {RedCloth}[http://redcloth.org]
+# * https://github.com/jgarber/redcloth
+
 require_relative 'template'
 require 'redcloth'
 
-# RedCloth implementation. See: https://github.com/jgarber/redcloth
 Tilt::RedClothTemplate = Tilt::StaticTemplate.subclass do
   engine = RedCloth.new(@data)
   @options.each  do |k, v|
diff --git a/lib/tilt/rst-pandoc.rb b/lib/tilt/rst-pandoc.rb
index afff5d7..0dd18b6 100644
--- a/lib/tilt/rst-pandoc.rb
+++ b/lib/tilt/rst-pandoc.rb
@@ -1,10 +1,33 @@
 # frozen_string_literal: true
+
+# = reStructuredText (<tt>rst</tt>)
+#
+# reStructuredText is a lightweight markup language originally developed by David Goodger,
+# based on StructuredText and Setext. reStructuredText is primarily used for technical
+# documentation in the Python programming language community, e.g. by the
+# {Sphinx}[http://www.sphinx-doc.org/en/stable/rest.html] Python documentation generator.
+#
+# reStructuredText formatted texts are converted to HTML with {Pandoc}[http://pandoc.org/], which
+# is an application written in Haskell, with a Ruby wrapper provided by the
+# {pandoc-ruby}[https://github.com/alphabetum/pandoc-ruby] gem.
+#
+# === Example
+#
+#     Hello Rst Templates
+#     ===================
+#
+#     Hello World. This is a paragraph.
+#
+# === See Also
+#
+# * {Pandoc}[http://pandoc.org/]
+# * {pandoc-ruby}[https://github.com/alphabetum/pandoc-ruby]
+
 require_relative 'template'
 require_relative 'pandoc'
 
 rst = {:f => "rst"}.freeze
 
-# Pandoc reStructuredText implementation. See: # http://pandoc.org/
 Tilt::RstPandocTemplate = Tilt::StaticTemplate.subclass do
   PandocRuby.new(@data, rst).to_html.strip
 end
diff --git a/lib/tilt/sass.rb b/lib/tilt/sass.rb
index 149d0b8..16b1d5d 100644
--- a/lib/tilt/sass.rb
+++ b/lib/tilt/sass.rb
@@ -1,10 +1,22 @@
 # frozen_string_literal: true
+
+# = Sass
+#
+# Sass template implementation for generating CSS.
+#
+# Sass templates do not support object scopes, locals, or yield.
+#
+# === See also
+#
+# * https://sass-lang.com/
+#
+# === Related module
+#
+# * Tilt::SassTemplate
+
 require_relative 'template'
 
 module Tilt
-  # Sass template implementation for generating CSS. See: https://sass-lang.com/
-  #
-  # Sass templates do not support object scopes, locals, or yield.
   class SassTemplate < StaticTemplate
     self.default_mime_type = 'text/css'
 
diff --git a/lib/tilt/slim.rb b/lib/tilt/slim.rb
index 2b50c4c..b0f7697 100644
--- a/lib/tilt/slim.rb
+++ b/lib/tilt/slim.rb
@@ -1,4 +1,17 @@
 # frozen_string_literal: true
+
+# = Slim (<tt>slim</tt>)
+#
+# === Embedded locals
+#
+# In slim templates, the comment format looks like this:
+#
+#   //# locals: ()
+#
+# === See also
+#
+# * https://slim-template.github.io
+
 require_relative 'template'
 require 'slim'
 
diff --git a/lib/tilt/string.rb b/lib/tilt/string.rb
index 59b2a2a..9f501b1 100644
--- a/lib/tilt/string.rb
+++ b/lib/tilt/string.rb
@@ -1,9 +1,17 @@
 # frozen_string_literal: true
+
+# = String
+#
+# The template source is evaluated as a Ruby string. The #{} interpolation
+# syntax can be used to generated dynamic output.
+#
+# === Related module
+#
+# * Tilt::StringTemplate
+
 require_relative 'template'
 
 module Tilt
-  # The template source is evaluated as a Ruby string. The #{} interpolation
-  # syntax can be used to generated dynamic output.
   class StringTemplate < Template
     def prepare
       hash = "TILT#{@data.hash.abs}"
diff --git a/lib/tilt/template.rb b/lib/tilt/template.rb
index 1654b54..515740a 100644
--- a/lib/tilt/template.rb
+++ b/lib/tilt/template.rb
@@ -41,12 +41,12 @@ def metadata
         @metadata ||= {}
       end
 
-      # Use `.metadata[:mime_type]` instead.
+      # Use <tt>.metadata[:mime_type]</tt> instead.
       def default_mime_type
         metadata[:mime_type]
       end
 
-      # Use `.metadata[:mime_type] = val` instead.
+      # Use <tt>.metadata[:mime_type] = val</tt> instead.
       def default_mime_type=(value)
         metadata[:mime_type] = value
       end
@@ -376,10 +376,10 @@ def local_extraction(local_keys)
 
       s = "locals = locals[:locals]"
       if assignments.delete(s)
-        # If there is a locals key itself named `locals`, delete it from the ordered keys so we can
+        # If there is a locals key itself named <tt>locals</tt>, delete it from the ordered keys so we can
         # assign it last. This is important because the assignment of all other locals depends on the
-        # `locals` local variable still matching the `locals` method argument given to the method
-        # created in `#compile_template_method`.
+        # <tt>locals</tt> local variable still matching the <tt>locals</tt> method argument given to the method
+        # created in <tt>#compile_template_method</tt>.
         assignments << s
       end
 
diff --git a/lib/tilt/typescript.rb b/lib/tilt/typescript.rb
index 19bcc02..6d71ba0 100644
--- a/lib/tilt/typescript.rb
+++ b/lib/tilt/typescript.rb
@@ -1,4 +1,9 @@
 # frozen_string_literal: true
+
+# = Typescript
+#
+# TypeScript implementation.
+
 require_relative 'template'
 require 'typescript-node'
 
diff --git a/lib/tilt/yajl.rb b/lib/tilt/yajl.rb
index 852daa0..2f2a92e 100644
--- a/lib/tilt/yajl.rb
+++ b/lib/tilt/yajl.rb
@@ -1,44 +1,54 @@
 # frozen_string_literal: true
+
+# = Yajl
+#
+# Yajl Template implementation
+#
+# Yajl is a fast JSON parsing and encoding library for Ruby
+#
+# The template source is evaluated as a Ruby string,
+# and the result is converted #to_json.
+#
+# === Example
+#
+#    # This is a template example.
+#    # The template can contain any Ruby statement.
+#    tpl <<-EOS
+#      @counter = 0
+#
+#      # The json variable represents the buffer
+#      # and holds the data to be serialized into json.
+#      # It defaults to an empty hash, but you can override it at any time.
+#      json = {
+#        :"user#{@counter += 1}" => { :name => "Joshua Peek", :id => @counter },
+#        :"user#{@counter += 1}" => { :name => "Ryan Tomayko", :id => @counter },
+#        :"user#{@counter += 1}" => { :name => "Simone Carletti", :id => @counter },
+#      }
+#
+#      # Since the json variable is a Hash,
+#      # you can use conditional statements or any other Ruby statement
+#      # to populate it.
+#      json[:"user#{@counter += 1}"] = { :name => "Unknown" } if 1 == 2
+#
+#      # The last line doesn't affect the returned value.
+#      nil
+#    EOS
+#
+#    template = Tilt::YajlTemplate.new { tpl }
+#    template.render(self)
+#
+# === See also
+#
+# * https://github.com/brianmario/yajl-ruby
+#
+# === Related module
+#
+# * Tilt::YajlTemplate
+
 require_relative 'template'
 require 'yajl'
 
 module Tilt
-  # Yajl Template implementation
-  #
-  # Yajl is a fast JSON parsing and encoding library for Ruby
-  # See https://github.com/brianmario/yajl-ruby
-  #
-  # The template source is evaluated as a Ruby string,
-  # and the result is converted #to_json.
-  #
-  # == Example
-  #
-  #    # This is a template example.
-  #    # The template can contain any Ruby statement.
-  #    tpl <<-EOS
-  #      @counter = 0
-  #
-  #      # The json variable represents the buffer
-  #      # and holds the data to be serialized into json.
-  #      # It defaults to an empty hash, but you can override it at any time.
-  #      json = {
-  #        :"user#{@counter += 1}" => { :name => "Joshua Peek", :id => @counter },
-  #        :"user#{@counter += 1}" => { :name => "Ryan Tomayko", :id => @counter },
-  #        :"user#{@counter += 1}" => { :name => "Simone Carletti", :id => @counter },
-  #      }
-  #
-  #      # Since the json variable is a Hash,
-  #      # you can use conditional statements or any other Ruby statement
-  #      # to populate it.
-  #      json[:"user#{@counter += 1}"] = { :name => "Unknown" } if 1 == 2
-  #
-  #      # The last line doesn't affect the returned value.
-  #      nil
-  #    EOS
-  #
-  #    template = Tilt::YajlTemplate.new { tpl }
-  #    template.render(self)
-  #
   class YajlTemplate < Template
     self.default_mime_type = 'application/json'