A Jekyll plugin that lets you embed code from GitHub repositories directly in your blog posts. Perfect for technical blogs, especially those using the Chirpy theme.
- Embed full files from any public GitHub repository
- Line range support - show only specific lines (
#L5-L15) - Automatic syntax highlighting using Rouge (Jekyll's built-in highlighter)
- Clickable filename links directly to GitHub
- Dark/light mode support compatible with Chirpy theme
- Graceful error handling with informative messages
Add this line to your Jekyll site's Gemfile:
gem 'jekyll-github-code'And then execute:
bundle installOr install it yourself as:
gem install jekyll-github-codeAdd the plugin to your _config.yml:
plugins:
- jekyll-github-codeThe plugin automatically copies the CSS file to your site's _site/assets/github-code/ directory during build.
Add the stylesheet to your layout's <head>:
<link rel="stylesheet" href="/assets/github-code/css/github-code.css">If you're using the Chirpy theme, add the link tag to _includes/head.html.
{% github_code owner/repo/blob/branch/path/to/file.py %}Example:
{% github_code r0x0d/toolbox-dev/blob/main/toolbox/environment/fedora-packaging.Containerfile %}Show only specific lines:
{% github_code owner/repo/blob/branch/path/to/file.py#L5-L15 %}Example:
{% github_code r0x0d/toolbox-dev/blob/main/toolbox/environment/fedora-packaging.Containerfile#L5-L15 %}{% github_code owner/repo/blob/branch/path/to/file.py#L10 %}You can also use the complete GitHub URL:
{% github_code https://github.com/owner/repo/blob/branch/path/to/file.py %}The plugin automatically detects the language from the file extension:
| Extension | Language |
|---|---|
.rb |
Ruby |
.py |
Python |
.js |
JavaScript |
.ts |
TypeScript |
.yml, .yaml |
YAML |
.md |
Markdown |
.sh |
Bash |
.Dockerfile, .Containerfile |
Dockerfile |
| Others | Uses extension as-is |
The plugin supports both light and dark themes out of the box, compatible with multiple theme systems:
[data-mode="light"]- Chirpy theme[data-theme="light"]- Common theme attribute.light- Class-based themes@media (prefers-color-scheme: light)- System preference
The default is dark theme. Light theme is automatically applied when any of the above selectors match.
You can customize the appearance by overriding CSS variables:
.github-code-block {
--github-code-bg: #0d1117;
--github-code-header-bg: #161b22;
--github-code-border: #30363d;
--github-code-text: #e6edf3;
--github-code-text-secondary: #8b949e;
--github-code-link: #58a6ff;
--github-code-link-hover: #79c0ff;
--github-code-copy-hover: #238636;
}Light theme values are automatically applied, but you can also customize them:
[data-mode="light"] .github-code-block {
--github-code-bg: #ffffff;
--github-code-header-bg: #f6f8fa;
--github-code-border: #d0d7de;
--github-code-text: #1f2328;
--github-code-text-secondary: #656d76;
--github-code-link: #0969da;
--github-code-link-hover: #0550ae;
}After checking out the repo, run bundle install to install dependencies.
bundle exec rake testOr run tests directly:
bundle exec ruby -Ilib -Itest test/github_code_test.rbbundle exec rake buildbundle exec rake installTo release a new version:
- Update the version number in
lib/jekyll-github-code/version.rb - Update
CHANGELOG.md - Run
bundle exec rake release
Open demo.html in your browser to see a preview of the rendered output with different examples.
- The Liquid tag parses the GitHub reference (owner/repo/branch/path)
- Fetches the raw file content from
raw.githubusercontent.com - Extracts the specified line range (if provided)
- Escapes HTML entities in the code
- Renders a styled code block with:
- GitHub icon and clickable filename
- Syntax-highlighted code
The plugin fetches code at build time. For production, consider:
- Using Jekyll caching plugins
- Setting up GitHub Actions with caching
- Pre-generating static includes for frequently used snippets
If the code cannot be fetched (e.g., 404, network error), the plugin displays a styled error message instead of breaking the build.
Bug reports and pull requests are welcome on GitHub at https://github.com/r0x0d/jekyll-github-code.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Add tests for new functionality
- Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
The gem is available as open source under the terms of the MIT License.