Jekyll vs GitHub Markdown Rendering Guide

The Problem

When publishing Markdown docs on GitHub Pages (which uses Jekyll), two main issues can occur:

1. Liquid Syntax Errors: Code samples containing template syntax (like {{ }} or {% %}) can cause Jekyll’s Liquid template processor to fail
2. Recursive Processing: Jekyll follows relative links in your README and tries to process ALL linked files, causing errors in files you never intended to be part of the Pages site

The Short Answer

Yes, adding {% raw %} tags will impact GitHub’s native Markdown rendering - these tags will appear as literal text when viewing the files directly on GitHub.

Visual Example

Here’s what happens in each context:

Your Original Markdown:

Here's a Vue.js example: {{ message }}

With Jekyll/Liquid Protection:

Here's a Vue.js example: {% raw %} {{ message }} {% endraw %}

How It Renders:

Context	Without {% raw %}	With {% raw %}
GitHub Repository View	✅ Shows {{ message }} correctly	❌ Shows the literal text {% raw %}{{ message }}{% endraw %}
GitHub Pages (Jekyll)	❌ Breaks - tries to process as Liquid	✅ Shows {{ message }} correctly

Pros and Cons

Pros of using {% raw %}:

• ✅ Your GitHub Pages site works correctly
• ✅ No Jekyll build errors
• ✅ Code examples display properly on the published site

Cons:

• ❌ Markdown files look messy when browsing the repo on GitHub
• ❌ Contributors see the wrapper tags in PRs and code reviews
• ❌ Less readable for developers working directly with the source

Alternative Solutions

1. Use HTML Entities

Works everywhere, but less readable in source:

Here's a Vue.js example: {{ message }}

2. Use Code Fences with Specific Syntax

Sometimes Jekyll is smart enough to not process code blocks:

```vue
{{ message }}
```

3. Configure Jekyll to Ignore Certain Files

In _config.yml:

exclude:
  - examples/*.md
  - code-samples/**/*.md

4. Use Alternative Delimiters

When possible, use different syntax in examples:

Here's a template example: [[message]] # Document that you're using alternate syntax

5. Use Jekyll’s raw Include Tag

Create an includes file:

_includes/raw-code.html

{% raw %}{{ include.code }}{% endraw %}

Then in your Markdown:

{% include raw-code.html code="{{ message }}" %}

The Best Solution: External Links

The most effective solution for GitHub Pages serving from root is to use absolute GitHub URLs for all documentation links. This prevents Jekyll from recursively processing linked files AND enables Mermaid diagram rendering.

Before (Problematic):

[Documentation](docs/) [How-to Guide](docs/how-to/configure.md)

After (Solution):

[Documentation](https://github.com/YourName/YourRepo/tree/main/docs)
[How-to Guide](https://github.com/YourName/YourRepo/blob/main/docs/how-to/configure.md)

Key Benefits:

• Mermaid Diagrams Work! - GitHub’s native rendering supports Mermaid diagrams, but GitHub Pages doesn’t without complex setup
• Jekyll treats these as external links and doesn’t process them
• Users can browse the repository directly with full GitHub features
• No need to modify your actual documentation files
• Works perfectly when GitHub Pages serves from repository root
• Avoids Liquid syntax processing errors

Important: If you want to render Mermaid diagrams, linking to the repository directly will allow that, so use the absolute URLs and just let visitors browse the repository for the details.

Alternative Solutions

For Content Within Your Pages Site

If you DO want certain Markdown files to be part of your Jekyll site:

1. HTML Entities - Use for simple inline examples
2. Code Fences - Jekyll usually handles these correctly
3. Jekyll Excludes - Use _config.yml to exclude specific directories

Recommendation

For GitHub Pages serving from root:

1. Use absolute GitHub URLs for all documentation links in your README
2. This prevents Jekyll from processing files containing Liquid syntax
3. Users can still access all documentation via GitHub’s native rendering
4. No need to modify documentation files with {% raw %} tags

Example Documentation Structure

/                       # GitHub Pages serves from here
├── README.md           # Landing page with absolute GitHub URLs
├── docs/               # Not processed by Jekyll (not linked relatively)
│   ├── guides/         # Contains Liquid syntax, viewed on GitHub
│   └── examples/       # Clean markdown, viewed on GitHub
└── _config.yml         # Optional Jekyll config (if needed)