switch fenced code blocks to AsciiDoc source blocks and always set language

23 files changed, 93 insertions, 74 deletions

diff --git a/docs/modules/ROOT/pages/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc
index 2e1bb934..2d39c52a 100644
--- a/docs/modules/ROOT/pages/localization-support.adoc
+++ b/docs/modules/ROOT/pages/localization-support.adoc
@@ -139,7 +139,7 @@ To use this file to translate the built-in labels according the value of the `la
 . Put the file in the folder [.path]_locale_ relative to your document.
 . Add the following line to the header of your AsciiDoc document:
 +
-[source]
+[source,asciidoc]
 ----
 \include::locale/attributes.adoc[]
 ----
diff --git a/docs/modules/extensions/pages/block-macro-processor.adoc b/docs/modules/extensions/pages/block-macro-processor.adoc
index df451c43..45ef1dc8 100644
--- a/docs/modules/extensions/pages/block-macro-processor.adoc
+++ b/docs/modules/extensions/pages/block-macro-processor.adoc
@@ -6,14 +6,16 @@ Create a block macro named `gist` for embedding a gist.
 
 == sample-with-gist-macro.adoc
 
-```
+[source,asciidoc]
+----
 .My Gist
 gist::123456[]
-```
+----
 
 == GistBlockMacro
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -35,14 +37,15 @@ class GistBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
     create_pass_block parent, html, attrs, subs: nil
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   block_macro GistBlockMacro if document.basebackend? 'html'
 end
 
 Asciidoctor.convert_file 'sample-with-gist.adoc', :safe => :safe
-```
+----
diff --git a/docs/modules/extensions/pages/block-processor.adoc b/docs/modules/extensions/pages/block-processor.adoc
index d228642e..fb04cbca 100644
--- a/docs/modules/extensions/pages/block-processor.adoc
+++ b/docs/modules/extensions/pages/block-processor.adoc
@@ -6,14 +6,16 @@ Register a custom block style named `shout` that uppercases all the words and co
 
 == sample-with-shout-block.adoc
 
-```
+[source,asciidoc]
+----
 [shout]
 The time is now. Get a move on.
-```
+----
 
 == ShoutBlock
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -32,14 +34,15 @@ class ShoutBlock < Asciidoctor::Extensions::BlockProcessor
     create_paragraph parent, (reader.lines.map {|l| l.upcase.gsub PeriodRx, '!' * volume }), attrs
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   block ShoutBlock
 end
 
 Asciidoctor.convert_file 'sample-with-shout-block.adoc', :safe => :safe
-```
+----
diff --git a/docs/modules/extensions/pages/compound-block-processor.adoc b/docs/modules/extensions/pages/compound-block-processor.adoc
index 32dea0e4..cd88a3b6 100644
--- a/docs/modules/extensions/pages/compound-block-processor.adoc
+++ b/docs/modules/extensions/pages/compound-block-processor.adoc
@@ -9,7 +9,7 @@ Register a custom block named `collapsible` that transforms a listing block into
 * the listing block is promoted to a source block if a language is specified using the second positional attribute.
 
 .sample-with-collapsible-block.adoc
-[source]
+[source,asciidoc]
 ....
 .Show JSON
 [collapsible,json]
diff --git a/docs/modules/extensions/pages/docinfo-processor.adoc b/docs/modules/extensions/pages/docinfo-processor.adoc
index d5510c1a..084937e3 100644
--- a/docs/modules/extensions/pages/docinfo-processor.adoc
+++ b/docs/modules/extensions/pages/docinfo-processor.adoc
@@ -6,7 +6,8 @@ Appends the Google Analytics tracking code to the bottom of an HTML document.
 
 == GoogleAnalyticsDocinfoProcessor
 
-```ruby
+[source,ruby]
+----
 class GoogleAnalyticsDocinfoProcessor < Asciidoctor::Extensions::DocinfoProcessor
   use_dsl
   at_location :footer
@@ -22,15 +23,16 @@ ga('send','pageview');
 </script>)
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   docinfo_processor GoogleAnalyticsDocinfoProcessor
 end
 
 Asciidoctor.convert_file 'sample.adoc', :safe => :safe,
     :attributes => 'UA-ABCXYZ123'
-```
+----
diff --git a/docs/modules/extensions/pages/include-processor.adoc b/docs/modules/extensions/pages/include-processor.adoc
index 8dbdd8e0..be27729a 100644
--- a/docs/modules/extensions/pages/include-processor.adoc
+++ b/docs/modules/extensions/pages/include-processor.adoc
@@ -8,7 +8,8 @@ TIP: Asciidoctor supports including content from a URI out of the box if you set
 
 == sample-with-uri-include.adoc
 
-```
+[source,asciidoc]
+....
 :source-highlighter: coderay
 
 .Gemfile
@@ -16,11 +17,12 @@ TIP: Asciidoctor supports including content from a URI out of the box if you set
 ----
 \include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/Gemfile[]
 ----
-```
+....
 
 == UriIncludeProcessor
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 require 'open-uri'
@@ -36,14 +38,15 @@ class UriIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
     reader
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   include_processor UriIncludeProcessor
 end
 
 Asciidoctor.convert_file 'sample-with-uri-include.adoc', :safe => :safe
-```
+----
diff --git a/docs/modules/extensions/pages/inline-macro-processor.adoc b/docs/modules/extensions/pages/inline-macro-processor.adoc
index b8d88b0e..69a8b89e 100644
--- a/docs/modules/extensions/pages/inline-macro-processor.adoc
+++ b/docs/modules/extensions/pages/inline-macro-processor.adoc
@@ -6,13 +6,15 @@ Create an inline macro named `man` that links to a manpage.
 
 == sample-with-man-link.adoc
 
-```
+[source,asciidoc]
+----
 See man:gittutorial[7] to get started.
-```
+----
 
 == ManpageInlineMacro
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -35,14 +37,15 @@ class ManInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
     %(#{(create_anchor parent, text, type: :link, target: target).convert}#{suffix})
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   inline_macro ManInlineMacro
 end
 
 Asciidoctor.convert_file 'sample-with-man-link.adoc', :safe => :safe
-```
+----
diff --git a/docs/modules/extensions/pages/postprocessor.adoc b/docs/modules/extensions/pages/postprocessor.adoc
index 712706ea..61be2401 100644
--- a/docs/modules/extensions/pages/postprocessor.adoc
+++ b/docs/modules/extensions/pages/postprocessor.adoc
@@ -6,7 +6,8 @@ Insert copyright text in the footer.
 
 == CopyrightFooterPostprocessor
 
-```ruby
+[source,ruby]
+----
 class CopyrightFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
   def process document, output
     content = (document.attr 'copyright') || 'Copyright Acme, Inc.'
@@ -20,14 +21,15 @@ class CopyrightFooterPostprocessor < Asciidoctor::Extensions::Postprocessor
     output
   end
 end
-```
+----
 
 == Usage
 
-```
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   postprocessor CopyrightFooterPostprocessor
 end
 
 Asciidoctor.convert_file 'sample-with-copyright-footer.adoc', :safe => :safe
-```
+----
diff --git a/docs/modules/extensions/pages/preprocessor.adoc b/docs/modules/extensions/pages/preprocessor.adoc
index c1e5a406..aa32516c 100644
--- a/docs/modules/extensions/pages/preprocessor.adoc
+++ b/docs/modules/extensions/pages/preprocessor.adoc
@@ -6,26 +6,27 @@ Skim off front matter from the top of the document that gets used by site genera
 
 == sample-with-front-matter.adoc
 
-```
----
+[source,asciidoc]
+----
 tags: [announcement, website]
 ---
 = Document Title
 
 content
 
-[subs="attributes,specialcharacters"]
+[subs=+attributes]
 .Captured front matter
 ....
 ---
 {front-matter}
 ---
 ....
-```
+----
 
 == FrontMatterPreprocessor
 
-```ruby
+[source,ruby]
+----
 require 'asciidoctor'
 require 'asciidoctor/extensions'
 
@@ -53,14 +54,15 @@ class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor
     reader
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   preprocessor FrontMatterPreprocessor
 end
 
 Asciidoctor.convert_file 'sample-with-front-matter.adoc', :safe => :safe
-```
+----
diff --git a/docs/modules/extensions/pages/register.adoc b/docs/modules/extensions/pages/register.adoc
index 7e076ba1..468398ef 100644
--- a/docs/modules/extensions/pages/register.adoc
+++ b/docs/modules/extensions/pages/register.adoc
@@ -4,7 +4,8 @@
 
 These extensions are registered per document using a callback that feels like a DSL:
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do |document|
   preprocessor FrontMatterPreprocessor
   tree_processor ShellSessionTreeProcessor
@@ -15,7 +16,7 @@ Asciidoctor::Extensions.register do |document|
   inline_macro ManInlineMacro
   include_processor UriIncludeProcessor
 end
-```
+----
 
 CAUTION: Extension classes must be defined outside of the register block.
 Once an extension class is registered, it is frozen, preventing further modification.
diff --git a/docs/modules/extensions/pages/tree-processor.adoc b/docs/modules/extensions/pages/tree-processor.adoc
index 050737ed..00a66436 100644
--- a/docs/modules/extensions/pages/tree-processor.adoc
+++ b/docs/modules/extensions/pages/tree-processor.adoc
@@ -6,16 +6,18 @@ Detect literal blocks that contain shell commands, strip the prompt character an
 
 == sample-with-shell-session.adoc
 
-```
+[source,asciidoc]
+----
  $ echo "Hello, World!"
  > Hello, World!
 
  $ gem install asciidoctor
-```
+----
 
 == ShellSessionTreeProcessor
 
-```ruby
+[source,ruby]
+----
 class ShellSessionTreeProcessor < Asciidoctor::Extensions::TreeProcessor
   def process document
     return unless document.blocks?
@@ -53,17 +55,18 @@ class ShellSessionTreeProcessor < Asciidoctor::Extensions::TreeProcessor
     create_listing_block block.document, lines * EOL, attrs, subs: nil
   end
 end
-```
+----
 
 == Usage
 
-```ruby
+[source,ruby]
+----
 Asciidoctor::Extensions.register do
   tree_processor ShellSessionTreeProcessor
 end
 
 Asciidoctor.convert_file 'sample-with-shell-session.adoc', :safe => :safe
-```
+----
 
 ////
 In the example below the TreeProcessor examines the block contents looking for the `// (*)` suffix and rewrites the line so that Asciidoctor formats it appropriately.
diff --git a/docs/modules/html-backend/pages/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc
index c3615dfe..578681f4 100644
--- a/docs/modules/html-backend/pages/custom-stylesheet.adoc
+++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc
@@ -30,7 +30,7 @@ Now let's use the `stylesheet` attribute to apply it.
 The `stylesheet` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :stylesheet: my-stylesheet.css
@@ -77,7 +77,7 @@ Now we need to tell Asciidoctor where it's located using `stylesdir`.
 The `stylesdir` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :stylesheet: my-stylesheet.css
@@ -190,14 +190,14 @@ Let's say you have three AsciiDoc documents saved in the following directory str
 
 For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to:
 
-[source]
+[source,asciidoc]
 ----
 :stylesdir: my-styles
 ----
 
 For [.path]_c.adoc_, set `stylesdir` to:
 
-[source]
+[source,asciidoc]
 ----
 :stylesdir: ../my-styles
 ----
diff --git a/docs/modules/html-backend/pages/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc
index 10672215..8b2fdd90 100644
--- a/docs/modules/html-backend/pages/stylesheet-modes.adoc
+++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc
@@ -32,7 +32,7 @@ If the `linkcss` document attribute is set, the converter will take this hint to
 The `linkcss` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :linkcss:
@@ -93,7 +93,7 @@ To prevent Asciidoctor from copying the stylesheet independent of safe mode, uns
 The `copycss` document attribute must be unset by the end of the header to be effective.
 One way to do that is to unset the attribute in the document header:
 
-[source]
+[source,asciidoc]
 ----
 = My First Experience with the Dangers of Documentation
 :linkcss:
diff --git a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
index f38b7daa..a032a193 100644
--- a/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
+++ b/docs/modules/html-backend/pages/verbatim-line-wrap.adoc
@@ -30,7 +30,7 @@ include::example$wrap.adoc[tag=nowrap]
 To prevent lines from wrapping globally, unset the `prewrap` attribute on the document.
 
 .Disable prewrap globally (thus, enabling nowrap)
-[source]
+[source,asciidoc]
 ----
 :prewrap!:
 ----
diff --git a/docs/modules/install/pages/ruby-packaging.adoc b/docs/modules/install/pages/ruby-packaging.adoc
index a07cfe16..8dbf98c8 100644
--- a/docs/modules/install/pages/ruby-packaging.adoc
+++ b/docs/modules/install/pages/ruby-packaging.adoc
@@ -25,7 +25,7 @@ To install a pre-release version of Asciidoctor (e.g., a release candidate), ope
 . Create a Gemfile in the root folder of your project (or the current directory)
 . Add the `asciidoctor` gem to your Gemfile as follows:
 +
-[source,subs=attributes+]
+[source,ruby,subs=attributes+]
 ----
 source 'https://rubygems.org'
 gem 'asciidoctor'
diff --git a/docs/modules/install/pages/windows.adoc b/docs/modules/install/pages/windows.adoc
index 2248b0b1..99d29b1e 100644
--- a/docs/modules/install/pages/windows.adoc
+++ b/docs/modules/install/pages/windows.adoc
@@ -6,10 +6,7 @@ To install Asciidoctor on Windows, you can use Chocolatey or Rubyinstaller.
 
 When you already use https://chocolatey.org[chocolatey^] on your machine, you can use:
 
-[source]
-----
-choco install ruby
-----
+ C:\> choco install ruby
 
 Then follow the xref:ruby-packaging.adoc[gem installation instructions].
 
diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index f9424cdf..1391f1c3 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -333,7 +333,7 @@ This content needs to be move to the specific subject docs pages if applicable
 Asciidoctor has shorthand for id, role, style and options.
 The following longhand syntax in AsciiDoc.py:
 
-[source]
+[source,asciidoc]
 ----
 [[id]]
 [style,role="role",options="option1,option2"]
@@ -341,7 +341,7 @@ The following longhand syntax in AsciiDoc.py:
 
 can be written using the shorthand supported by Asciidoctor:
 
-[source]
+[source,asciidoc]
 ----
 [style#id.role%option1%option2]
 ----
diff --git a/docs/modules/stem/pages/asciimath-gem.adoc b/docs/modules/stem/pages/asciimath-gem.adoc
index 5016bacd..08a940cb 100644
--- a/docs/modules/stem/pages/asciimath-gem.adoc
+++ b/docs/modules/stem/pages/asciimath-gem.adoc
@@ -41,7 +41,7 @@ First, activate STEM support in AsciiDoc by setting the `stem` document attribut
 This attribute must be set by the end of the document header.
 
 .Activate STEM support by setting the stem document attribute
-[source]
+[source,asciidoc]
 ----
 = Document Title
 :stem:
diff --git a/docs/modules/syntax-highlighting/pages/coderay.adoc b/docs/modules/syntax-highlighting/pages/coderay.adoc
index c7b035a9..1eba3525 100644
--- a/docs/modules/syntax-highlighting/pages/coderay.adoc
+++ b/docs/modules/syntax-highlighting/pages/coderay.adoc
@@ -60,7 +60,7 @@ Install using dnf (Fedora-based systems)::
 
 Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: coderay
 ----
@@ -81,7 +81,7 @@ If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you wa
 Default: `table`.
 
 .Customizing a source block with CodeRay line numbers
-[source]
+[source,asciidoc]
 ....
 :source-highlighter: coderay
 :coderay-linenums-mode: inline
diff --git a/docs/modules/syntax-highlighting/pages/highlightjs.adoc b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
index ab9c2fc3..c1f95543 100644
--- a/docs/modules/syntax-highlighting/pages/highlightjs.adoc
+++ b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
@@ -9,7 +9,7 @@
 
 To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file:
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: highlight.js
 ----
@@ -25,7 +25,7 @@ Separate each language by a comma followed by an optional space.
 The common highlight.js bundle does not include support for Rust and Swift.
 Let's set the `highlightjs-languages` attribute so the HTML converter loads support for them into the HTML page.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: highlight.js
 :highlightjs-languages: rust, swift
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
index 153e0907..ad858d1f 100644
--- a/docs/modules/syntax-highlighting/pages/index.adoc
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -3,7 +3,7 @@
 AsciiDoc defines a style of listing block known as a source block for adding a source code listing to a document that's intended to be colorized by a syntax highlighter.
 Here's a simple example of a source block:
 
-[source]
+[source,asciidoc]
 ....
 [source,ruby]
 ----
diff --git a/docs/modules/syntax-highlighting/pages/pygments.adoc b/docs/modules/syntax-highlighting/pages/pygments.adoc
index a049b690..6efa59b6 100644
--- a/docs/modules/syntax-highlighting/pages/pygments.adoc
+++ b/docs/modules/syntax-highlighting/pages/pygments.adoc
@@ -32,7 +32,7 @@ $ gem install pygments.rb # <.>
 
 Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: pygments
 ----
@@ -59,7 +59,7 @@ If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you wa
 Default: `table`.
 
 .Customizing a source block with Pygments attributes
-[source]
+[source,asciidoc]
 ....
 :source-highlighter: pygments
 :pygments-style: manni
diff --git a/docs/modules/syntax-highlighting/pages/rouge.adoc b/docs/modules/syntax-highlighting/pages/rouge.adoc
index b6022864..2cb56468 100644
--- a/docs/modules/syntax-highlighting/pages/rouge.adoc
+++ b/docs/modules/syntax-highlighting/pages/rouge.adoc
@@ -26,7 +26,7 @@ Install using `dnf` (Fedora-based systems)::
 
 Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it.
 
-[source]
+[source,asciidoc]
 ----
 :source-highlighter: rouge
 ----
@@ -51,7 +51,7 @@ Controls the color theme used to for highlighting.
 You can find the list of themes in the {url-rouge-repo}[Rouge code repository^].
 
 .Customizing a source block with Rouge line numbers
-[source]
+[source,asciidoc]
 ....
 :source-highlighter: rouge