Improve the "Markdown Options" Docs

[mkasberg]

This is a 🔦 documentation change.

Summary

It seems the Markdown Options docs have become out of date, as noted in
#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 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.

Context

Fixes #8593

[github-actions]

@check-spelling-bot Report

Unrecognized words, please review:

• rubychan

Previously acknowledged words that are now absent

backlink EOL

To accept these unrecognized words as correct (and remove the previously acknowledged and now absent words), run the following commands

... in a clone of the git@github.com:mkasberg/jekyll.git repository
on the docs-markdown-config branch:

update_files() {
perl -e '
my @expect_files=qw('".github/actions/spelling/expect.txt"');
@ARGV=@expect_files;
my @stale=qw('"$patch_remove"');
my $re=join "|", @stale;
my $suffix=".".time();
my $previous="";
sub maybe_unlink { unlink($_[0]) if $_[0]; }
while (<>) {
if ($ARGV ne $old_argv) { maybe_unlink($previous); $previous="$ARGV$suffix"; rename($ARGV, $previous); open(ARGV_OUT, ">$ARGV"); select(ARGV_OUT); $old_argv = $ARGV; }
next if /^(?:$re)(?:(?:\r|\n)*$| .*)/; print;
}; maybe_unlink($previous);'
perl -e '
my $new_expect_file=".github/actions/spelling/expect.txt";
use File::Path qw(make_path);
use File::Basename qw(dirname);
make_path (dirname($new_expect_file));
open FILE, q{<}, $new_expect_file; chomp(my @words = <FILE>); close FILE;
my @add=qw('"$patch_add"');
my %items; @items{@words} = @words x (1); @items{@add} = @add x (1);
@words = sort {lc($a)."-".$a cmp lc($b)."-".$b} keys %items;
open FILE, q{>}, $new_expect_file; for my $word (@words) { print FILE "$word\n" if $word =~ /\w/; };
close FILE;
system("git", "add", $new_expect_file);
'
}

comment_json=$(mktemp)
curl -L -s -S \
  --header "Content-Type: application/json" \
  "https://api.github.com/repos/jekyll/jekyll/issues/comments/842753244" > "$comment_json"
comment_body=$(mktemp)
jq -r .body < "$comment_json" > $comment_body
rm $comment_json

patch_remove=$(perl -ne 'next unless s{^</summary>(.*)</details>$}{$1}; print' < "$comment_body")
  

patch_add=$(perl -e '$/=undef;
$_=<>;
s{<details>.*}{}s;
s{^#.*}{};
s{\n##.*}{};
s{(?:^|\n)\s*\*}{}g;
s{\s+}{ }g;
print' < "$comment_body")
  
update_files
rm $comment_body
git add -u

If you see a bunch of garbage

If it relates to a ...

well-formed pattern

See if there's a pattern that would match it.

If not, try writing one and adding it to the patterns.txt file.

Patterns are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your lines.

Note that patterns can't match multiline strings.

binary-ish string

Please add a file path to the excludes.txt file instead of just accepting the garbage.

File paths are Perl 5 Regular Expressions - you can test yours before committing to verify it will match your files.

^ refers to the file's path from the root of the repository, so ^README\.md$ would exclude README.md (on whichever branch you're using).

[DirtyF]

Thanks, this looks good to me.

[crispgm]

👍🏻

[DirtyF]

@jekyll: merge +docs

Thanks for the review @crispgm 🙏