Improve the "Markdown Options" Docs #8681

mkasberg · 2021-05-18T01:27:41Z

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 · 2021-05-18T01:28:08Z

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

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

DirtyF

Thanks, this looks good to me.

docs/_docs/configuration/markdown.md

crispgm

👍🏻

DirtyF · 2021-05-18T07:34:13Z

@jekyll: merge +docs

Thanks for the review @crispgm 🙏

Mike Kasberg: Improve the "Markdown Options" Docs (#8681) Merge pull request 8681

I recently merged jekyll#8681 to improve the Jekyll docs for markdown options. While researching that, I noted that the `kramdown-parser-gfm` gem is required by default in Jekyll, but I didn't dig further as to why. After jekyll#8681 merged, I was curious about why `kramdown-parser-gfm` is required by default, and I followed up on digging into it. As it turns out, this GFM parser is required by default because Jekyll uses GFM by default. This is clear from the [default config docs](https://jekyllrb.com/docs/configuration/default/) and the code: https://github.com/jekyll/jekyll/blob/76517175e700d80706c9139989053f1c53d9b956/lib/jekyll/configuration.rb#L67-L72 Although this is outlined in the default configuration docs, other parts of the docs don't do a good job making it clear that GFM is actually the default behavior. My recent docs change in jekyll#8681 made this problem worse since I used a bunch of config in my examples that's actually just default config. In this PR, I'm addressing that problem by modifying my update to the Markdown Options docs to clearly note that GFM is the default parser. I'm also updating a tutorial that implied GFM isn't the default. I've searched this repo for "GFM" and I'm pretty confident I've found all the problematic docs.

mkasberg mentioned this pull request May 18, 2021

docs: update markdown options to kramdown 2 #8593

Closed

mkasberg force-pushed the docs-markdown-config branch from 24f5a4d to 868c816 Compare May 18, 2021 01:52

DirtyF requested review from a team and crispgm and removed request for a team May 18, 2021 06:34

DirtyF added the documentation label May 18, 2021

DirtyF approved these changes May 18, 2021

View reviewed changes

docs/_docs/configuration/markdown.md Outdated Show resolved Hide resolved

docs/_docs/configuration/markdown.md Outdated Show resolved Hide resolved

DirtyF added 2 commits May 18, 2021 08:38

Update docs/_docs/configuration/markdown.md

0c4c81a

Update docs/_docs/configuration/markdown.md

3685d49

crispgm approved these changes May 18, 2021

View reviewed changes

jekyllbot merged commit b5e910a into jekyll:master May 18, 2021

jekyllbot added a commit that referenced this pull request May 18, 2021

Update history to reflect merge of #8681 [ci skip]

7651717

github-actions bot pushed a commit that referenced this pull request May 18, 2021

Deploy docs from b5e910a

7ce8f09

Mike Kasberg: Improve the "Markdown Options" Docs (#8681) Merge pull request 8681

mkasberg mentioned this pull request May 19, 2021

Improve GitHub Flavored Markdown Docs #8684

Merged

jekyll locked and limited conversation to collaborators May 18, 2022

jekyllbot added the frozen-due-to-age label May 18, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the "Markdown Options" Docs #8681

Improve the "Markdown Options" Docs #8681

Improve the "Markdown Options" Docs #8681

Improve the "Markdown Options" Docs #8681

Conversation

Summary

Context

@check-spelling-bot Report

Unrecognized words, please review:

Choose a reason for hiding this comment

Choose a reason for hiding this comment