Improve the "Markdown Options" Docs (#8681)

Merge pull request 8681

.github/actions/spelling/expect.txt

@@ -34,7 +34,6 @@ awood
 aws
 awscli
 backend
-backlink
 backport
 backtick
 barcamp
@@ -165,7 +164,6 @@ endraw
 endrender
 endtablerow
 Enumerables
-EOL
 eol
 erb
 errordocument
@@ -528,6 +526,7 @@ rsync
 rtomayko
 Rubo
 rubocop
+rubychan
 rubygem
 rubyinstaller
 rubyprof

docs/_docs/configuration/markdown.md

@@ -5,61 +5,63 @@ permalink: "/docs/configuration/markdown/"
 The various Markdown renderers supported by Jekyll sometimes have extra options
 available.
 
-### Kramdown
+## Kramdown
 
-Kramdown is the default Markdown renderer for Jekyll. Below is a list of the
-currently supported options:
+Kramdown is the default Markdown renderer for Jekyll, and often works well with no additional configuration. However, it does support many configuration options.
 
-* **auto_id_prefix** - Prefix used for automatically generated header IDs
-* **auto_id_stripping** - Strip all formatting from header text for automatic ID generation
-* **auto_ids** - Use automatic header ID generation
-* **coderay_bold_every** - Defines how often a line number should be made bold
-* **coderay_css** - Defines how the highlighted code gets styled
-* **coderay_default_lang** - Sets the default language for highlighting code blocks
-* **coderay_line_number_start** - The start value for the line numbers
-* **coderay_line_numbers** - Defines how and if line numbers should be shown
-* **coderay_tab_width** - The tab width used in highlighted code
-* **coderay_wrap** - Defines how the highlighted code should be wrapped
-* **enable_coderay** - Use coderay for syntax highlighting
-* **entity_output** - Defines how entities are output
-* **footnote_backlink** - Defines the text that should be used for the footnote backlinks
-* **footnote_backlink_inline** - Specifies whether the footnote backlink should always be inline
-* **footnote_nr** - The number of the first footnote
-* **gfm_quirks** - Enables a set of GFM specific quirks
-* **hard_wrap** - Interprets line breaks literally
-* **header_offset** - Sets the output offset for headers
-* **html_to_native** - Convert HTML elements to native elements
-* **line_width** - Defines the line width to be used when outputting a document
-* **link_defs** - Pre-defines link definitions
-* **math_engine** - Set the math engine
-* **math_engine_opts** - Set the math engine options
-* **parse_block_html** - Process kramdown syntax in block HTML tags
-* **parse_span_html** - Process kramdown syntax in span HTML tags
-* **smart_quotes** - Defines the HTML entity names or code points for smart quote output
-* **syntax_highlighter** - Set the syntax highlighter
-* **syntax_highlighter_opts** - Set the syntax highlighter options
-* **toc_levels** - Defines the levels that are used for the table of contents
-* **transliterated_header_ids** - Transliterate the header text before generating the ID
-* **typographic_symbols** - Defines a mapping from typographical symbol to output characters
+### GitHub Flavored Markdown
+
+Kramdown supports GitHub Flavored Markdown (GFM). To use GFM with Kramdown in Jekyll, add the following to your configuration.
 
-### Example Usage
 ```yaml
 kramdown:
-  html_to_native: true
+  input: GFM
+```
+
+GFM supports additional Kramdown options, documented at [kramdown-parser-gfm](https://github.com/kramdown/parser-gfm). These options can be used directly in your Kramdown Jekyll config, like this:
+
+```yaml
+kramdown:
+  input: GFM
+  gfm_quirks: [paragraph_end]
+```
+
+### Syntax Highlighting (CodeRay)
+
+To use the [CodeRay](http://coderay.rubychan.de/) syntax highlighter with Kramdown, you  need to add a dependency on the `kramdown-syntax-coderay` gem. For example, `bundle add kramdown-syntax-coderay`. Then, you'll be able to specify CodeRay in your `syntax_highlighter` config:
+
+```yaml
+kramdown:
+  syntax_highlighter: coderay
+```
+
+CodeRay supports several of its own configuration options, documented in the [kramdown-syntax-coderay docs](https://github.com/kramdown/syntax-coderay) which can be passed as `syntax_highlighter_opts` like this:
+
+```yaml
+kramdown:
+  syntax_highlighter: coderay
+  syntax_highlighter_opts:
+    line_numbers: table
+    bold_every: 5
+```
+
+### Advanced Kramdown Options
+
+Kramdown supports a variety of other relatively advanced options such as `header_offset` and `smart_quotes`. These are documented in the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html) and can be added to your Kramdown config like this:
+
+```yaml
+kramdown:
+  header_offset: 2
 ```
 
 <div class="note warning">
-  <h5>There are two unsupported kramdown options</h5>
+  <h5>There are several unsupported kramdown options</h5>
   <p>
-    Please note that both <code>remove_block_html_tags</code> and
-    <code>remove_span_html_tags</code> are currently unsupported in Jekyll due
-    to the fact that they are not included within the kramdown HTML converter.
+    Please note that Jekyll uses Kramdown's HTML converter. Kramdown options used only by other converters, such as <code>remove_block_html_tags</code> (used by the RemoveHtmlTags converter), will not work.
   </p>
 </div>
 
-For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html).
-
-### CommonMark
+## CommonMark
 
 [CommonMark](https://commonmark.org/) is a rationalized version of Markdown syntax, implemented in C and thus faster than default Kramdown implemented in Ruby. It [slightly differs](https://github.com/commonmark/CommonMark#differences-from-original-markdown) from original Markdown and does not support all the syntax elements implemented in Kramdown, like [Block Inline Attribute Lists](https://kramdown.gettalong.org/syntax.html#block-ials).