Markdown Processor Choice in Jekyll 4.0: Enabling GitHub Flavored Markdown via jekyll-commonmark

jekyll-commonmark is a reasonable default for new Jekyll 4.x sites that must author in GitHub Flavored Markdown, but it is not a safe drop-in replacement for existing kramdown content. The gem changes the Markdown dialect, sits outside the core Jekyll distribution, and carries no official compatibility guarantee for future releases. The one diagnostic that changes the recommendation is whether your content already contains kramdown-specific syntax; if it does, audit before switching.

Confirmed setup and likely drift

Enabling GFM requires both the gem in the Gemfile and markdown: CommonMark in _config.yml; if either is missing, Jekyll keeps kramdown or fails to load the converter, and the server must be restarted after changes. The likely explanation for rendering drift is that kramdown and CommonMark are different parsers with different extension sets. kramdown supports footnotes, definition lists, attribute lists, and certain table edge cases that are outside CommonMark core, so enabling CommonMark can silently alter or break pages using those features. Heading auto-id generation and link anchors may also change.

Risks for new sites

• Dependency lock-in: jekyll-commonmark is an optional gem with no guarantee from the Jekyll project about future compatibility.
• Platform sensitivity: commonmarker can have platform-specific dependencies; build on the same platform as production to avoid environment-specific failures.
• Migration cost: content that later needs kramdown-only features may require a parser switch or syntax rewrite.

Effect on existing kramdown content

Existing kramdown syntax is not portable. Do not mix kramdown and CommonMark for the same content set; choose one processor per build to avoid inconsistent rendering. A conservative migration keeps kramdown for legacy pages, uses CommonMark only for new content after an audit, pins jekyll/jekyll-commonmark/commonmarker versions in Gemfile.lock, and compares generated HTML before changing the default.

Should Jekyll ship an official GFM mode?

An official built-in GFM mode would reduce third-party plugin risk and make builds more repeatable. It would also bind Jekyll to a GFM dialect and still not guarantee byte-identical output with GitHub Pages unless the same parser, extensions, and options are used on both sides. GitHub Pages runs a constrained whitelisted environment whose effective dialect may differ from a local jekyll-commonmark build, so parity remains a verification problem rather than a configuration guarantee.

Verification before switching

1. Build a fixture page containing footnotes, tables, attribute lists, fenced code, and task lists with kramdown, then with jekyll-commonmark, and diff the HTML in _site.
2. Run

   bundle exec jekyll build

   with the exact Gemfile.lock used for deployment and confirm the configured converter loads without errors or deprecation warnings.
3. Build the same repository on GitHub Pages or with the github-pages gem if that is the deploy target, then compare rendered HTML, anchors, and asset paths with the local CommonMark build.
4. Record jekyll, jekyll-commonmark, commonmarker, and kramdown versions from Gemfile.lock in site build documentation before switching defaults.

Jekyll 4.0 is an older release; later Jekyll versions, current GitHub Pages behavior, and gem compatibility may have changed. Treat the compatibility notes above as a planning baseline and verify against your own build output.