From 868c816624001e42ab0affec657f39a86003bc6a Mon Sep 17 00:00:00 2001 From: Mike Kasberg Date: Mon, 17 May 2021 19:06:10 -0600 Subject: [PATCH 1/3] Improve the "Markdown Options" Docs It seems the Markdown Options docs have become out of date, as noted in https://github.com/jekyll/jekyll/issues/8593. The docs most likely became out of date when Kramdown was updated to v2, as described in these release notes: https://jekyllrb.com/news/2020/08/05/jekyll-3-9-0-released/. Initially, I intended to fix the specific issue about `gfm_quirks` noted in #8593, but after digging a little deeper to figure out the correct way to use that option, it became apparent that other parts of the Markdown Options Jekyll docs were also outdated and the whole page needed to be updated to be more accurate and more useful for modern versions of Jekyll. So, with that in mind, here's an overview of the changes I'm proposing: * Adjust the page headings. `Kramdown` should be an `h2` and the Kramdown sub-headings should be `h3`. * Document modern config for the GFM parser via `input: GFM`. * Link to the CodeRay docs and provide an example of the correct `syntax_highlighter` config with `syntax_highlighter_opts`. * Link to the options supported by Kramdown and provide an example of their usage. * Remove the list of all the relatively advanced Kramdown options supported by Jekyll, directing users instead to the Kramdown docs. At a high level, this is a move away from attempting to document every supported Kramdown option on this page and a move toward linking to up-to-date documentation for the various gems we support. The old docs were outdated, and not as useful as the docs provided by individual gems because the Jekyll docs didn't provide thorough descriptions as the [Kramdown docs](https://kramdown.gettalong.org/options.html) do. I think my proposed change captures a good balance of showing example usage in Jekyll while still relying on the gems we depend on to provide thorough descriptions of the supported options. --- .github/actions/spelling/expect.txt | 3 +- docs/_docs/configuration/markdown.md | 96 ++++++++++++++-------------- 2 files changed, 50 insertions(+), 49 deletions(-) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index d6a6a589e86..3d557ca8fb5 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 d06743d876b..f9aca3a9a8c 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 is the default Markdown renderer for Jekyll. Below is a list of the -currently supported 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 - -### Example Usage +## Kramdown + +Kramdown is the default Markdown renderer for Jekyll, and often works well with no additional configuration. However, it does support many configuration options that are available if you need them. + +### GitHub Flavored Markdown + +Kramdown supports GitHub Flavored Markdown (GFM). To use GFM with Kramdown in Jekyll, add the following to your configuration. + +```yaml +kramdown: + 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'll 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: - html_to_native: true + 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). From 0c4c81ae16a2657b2f75ed6213313bcf625d811a Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Tue, 18 May 2021 08:38:12 +0200 Subject: [PATCH 2/3] Update docs/_docs/configuration/markdown.md --- docs/_docs/configuration/markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/configuration/markdown.md b/docs/_docs/configuration/markdown.md index f9aca3a9a8c..c781050bdd1 100644 --- a/docs/_docs/configuration/markdown.md +++ b/docs/_docs/configuration/markdown.md @@ -7,7 +7,7 @@ available. ## Kramdown -Kramdown is the default Markdown renderer for Jekyll, and often works well with no additional configuration. However, it does support many configuration options that are available if you need them. +Kramdown is the default Markdown renderer for Jekyll, and often works well with no additional configuration. However, it does support many configuration options. ### GitHub Flavored Markdown From 3685d49679ac4028eb691fc3fb7145f44ee41f95 Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Tue, 18 May 2021 08:38:19 +0200 Subject: [PATCH 3/3] Update docs/_docs/configuration/markdown.md --- docs/_docs/configuration/markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/configuration/markdown.md b/docs/_docs/configuration/markdown.md index c781050bdd1..38904d7a2dd 100644 --- a/docs/_docs/configuration/markdown.md +++ b/docs/_docs/configuration/markdown.md @@ -28,7 +28,7 @@ kramdown: ### Syntax Highlighting (CodeRay) -To use the [CodeRay](http://coderay.rubychan.de/) syntax highlighter with Kramdown, you'll 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: +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: