From 0eb9239151323b11ddcd91bf2e61edefe990443f Mon Sep 17 00:00:00 2001 From: Mike Kasberg Date: Thu, 22 Jul 2021 11:57:51 -0600 Subject: [PATCH] Improve GitHub Flavored Markdown Docs (#8684) Merge pull request 8684 --- docs/_docs/configuration/markdown.md | 21 +++++++++++---------- docs/_tutorials/convert-site-to-jekyll.md | 14 ++++---------- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/docs/_docs/configuration/markdown.md b/docs/_docs/configuration/markdown.md index 38904d7a..9cd65a33 100644 --- a/docs/_docs/configuration/markdown.md +++ b/docs/_docs/configuration/markdown.md @@ -9,23 +9,24 @@ available. 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 +### Kramdown Processor -Kramdown supports GitHub Flavored Markdown (GFM). To use GFM with Kramdown in Jekyll, add the following to your configuration. +By default, Jekyll uses the [GitHub Flavored Markdown (GFM) processor](https://github.com/kramdown/parser-gfm) for Kramdown. (Specifying `input: GFM` is fine, but redundant.) GFM supports a couple additional Kramdown options, documented by [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 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] ``` +You can also change the processor used by Kramdown (as specified for the `input` key in the [Kramdown RDoc](https://kramdown.gettalong.org/rdoc/Kramdown/Document.html#method-c-new)). For example, to use the non-GFM Kramdown processor in Jekyll, add the following to your configuration. + +```yaml +kramdown: + input: Kramdown +``` + +Documentation for Kramdown parsers is available in the [Kramdown docs](https://kramdown.gettalong.org/parser/kramdown.html). If you use a Kramdown parser other than Kramdown or GFM, you'll need to add the gem for it. + ### 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: diff --git a/docs/_tutorials/convert-site-to-jekyll.md b/docs/_tutorials/convert-site-to-jekyll.md index 22b31c65..e31c0a1f 100644 --- a/docs/_tutorials/convert-site-to-jekyll.md +++ b/docs/_tutorials/convert-site-to-jekyll.md @@ -181,22 +181,16 @@ If you don't specify a layout in your pages, Jekyll will simply render that page ## 4. Add a configuration file -Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, [kramdown](https://kramdown.gettalong.org/) is used (without the need to specify it). If no other filter is specified, your config file will automatically apply the following as a default setting: +Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, the [GitHub Flavored Markdown (GFM) processor](https://github.com/kramdown/parser-gfm) for [kramdown](https://kramdown.gettalong.org/) is used. If no other filter is specified, your config file will automatically apply the following as a [default](/docs/configuration/default/) setting: ```yaml markdown: kramdown -``` - -You can also specify [some options](https://kramdown.gettalong.org/converter/html.html) for kramdown to make it behave more like [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/): - -```yaml kramdown: - input: GFM - auto_ids: true - hard_wrap: false - syntax_highlighter: rouge + input: GFM ``` +You can find additional [Markdown Options](/docs/configuration/markdown/) in the Jekyll docs, though it's unlikely that you'll need them. + ## 5. Test your pages Now run `jekyll serve` and toggle between your `index.html` and `about.html` pages. The default layout should load for both pages.