From b5e910acfbf0ea542ddb91e035847cdae168aebf Mon Sep 17 00:00:00 2001 From: Mike Kasberg Date: Tue, 18 May 2021 01:34:13 -0600 Subject: [PATCH] Improve the "Markdown Options" Docs (#8681) Merge pull request 8681 --- .github/actions/spelling/expect.txt | 3 +- docs/_docs/configuration/markdown.md | 90 ++++++++++++++-------------- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index de551310..b2cfe92c 100644 --- a/.github/actions/spelling/expect.txt +++ b/.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 diff --git a/docs/_docs/configuration/markdown.md b/docs/_docs/configuration/markdown.md index d06743d8..38904d7a 100644 --- a/docs/_docs/configuration/markdown.md +++ b/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 +``` +
-
There are two unsupported kramdown options
+
There are several unsupported kramdown options

- Please note that both remove_block_html_tags and - remove_span_html_tags 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 remove_block_html_tags (used by the RemoveHtmlTags converter), will not work.

-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).