Kickstart Blogging with Chirpy
- How Chirpy Is Structured: Starter Project + Core Theme
- Getting Started with the chirpy starter and Deploying Using GitHub Actions
- Styling and Typography Tips to Improve Your Blog
- Basic Markdown Elements (Standard)
- Advanced Styling and Syntax with Markdown, Kramdown, and Chirpy
- Special thanks to Cotes and all the contributors
How Chirpy Is Structured: Starter Project + Core Theme
Chirpy is a modern, feature-rich Jekyll theme designed for blogging and documentation. It’s split into two main repositories that work together seamlessly:
chirpy-starterandjekyll-theme-chirpy
🔸 The Core Theme — jekyll-theme-chirpy
This is the core theme repository, which contains all the actual theme logic data and assets:
- Layouts (
_layouts/) - Includes (
_includes/) - Styles and scripts (
assets/) - Page templates
- Core logic of the Chirpy theme
- Config defaults and helper functions
Internal Structure of Chirpy Core Theme. Inside jekyll-theme-chirpy, you’ll find:
1
2
3
4
5
6
7
8
Folder/File Purpose
`_layouts/` HTML templates defining page structure (default, post, page, home, categories, etc.)
`_includes/` Reusable components (headers, footers, sidebar widgets, post metadata)
`_sass/` Sass partials and variables for styling
`assets/` Static files: CSS, JS, images, fonts
`_data/` YAML data files for menus, socials, assets config
`_config.yml` Default theme config, overwritten by starter’s config
🔹 Starter Project – chirpy-starter
This is the starter project — a ready-to-use Jekyll site with Chirpy already configured.
This is usually the best way to go for almost all of your work.
It includes:
- Example posts
Gemfilewith theme dependency_config.ymlwith pre-set configurations- GitHub Actions workflow for Pages deployment (
.github/workflows/pages-deploy.yml) - A folder structure suitable for customization and development
This acts as a boilerplate blueprint to help you kick off a new blog quickly and efficiently.
Key Features
Integrated Theme Setup:
TheGemfilealready includes thejekyll-theme-chirpygem. Runningbundle installwill fetch and install the core theme.Pre-configured Deployment Workflow:
The GitHub Actions workflow (pages-deploy.yml) is already set up. No manual deployment script is needed — just push and publish!Theme Included via
_config.yml:
The_config.ymlfile already references the core theme and provides all necessary flags and options you can easily customize.Customizable via Overrides:
You can override any core theme file by creating your own versions in:_data/— override default site data (e.g., navigation, authors)_layouts/— override layout templates_includes/,assets/, and other folders as needed
You don’t see these theme files (except limited files in
_data/andassets/) directly in the starter repo because they’re loaded from the theme gem (jekyll-theme-chirpy). But they are overrideable. and also can containyou custome files and folders as well
- example the
assets/can haveassets/my_asset_files_or_folders/filessscd.png
How It Works
When you use the starter repo and run bundle install, the core theme is installed and pulled into your project. It is referenced in your _config.yml and Gemfile like this (this is already provided no need to do anytng):
1
gem "jekyll-theme-chirpy", "~> 7.3", ">= 7.3.1"
1
2
theme: jekyll-theme-chirpy
This tells Jekyll to use theme’s layouts (installed in this case), includes, CSS, and other assets from the core repo at build time.
The starter project then adds:
Site-specific content: posts, pages, custom config, and data files.
Customization or overrides: any local files in _layouts, _includes, or assets in the starter repo override those from the theme.
Note: You can use the following to pull the remote theme directly from the GitHub repo: However, this is not required and generally not advised.
Stick to the boilerplate method (chirpy-starter), which is simpler, more reliable, and comes pre-configured without any compromises.
1 2 remote_theme: jekyll-theme-chirpy
Getting Started with the chirpy starter and Deploying Using GitHub Actions
Styling and Typography Tips to Improve Your Blog
Chirpy supports all standard Markdown syntax and provides additional typographic enhancements to make your content more readable, highlighted, and visually appealing.
Basic Markdown Elements (Standard)
These are universal Markdown features, and they work out of the box with Chirpy.
| Feature | Markdown Syntax | Rendered Output in Chirpy |
|---|---|---|
| Heading | # to ###### | Section titles (h1–h6) |
| Bold | **bold** | bold |
| Italic | *italic* or | italic |
| Bold Italic | ***text*** | text |
| Inline Code | `code` | code |
| Blockquote | > This is a quote | Styled blockquote |
| Lists | - Item or 1. Item or * Item | Bulleted or numbered list |
| Horizontal Line | ---, ***, or ___ | Divider line (horizontal rule) |
| Links | [OpenAI](https://openai.com) | OpenAI |
| Images |  | Embedded image |
Block Quote
1
> This line shows the _block quote_.
This line shows the block quote.
Advanced Styling and Syntax with Markdown, Kramdown, and Chirpy
Code blocks
Markdown symbols ``` can easily create a code block as follows:
1
2
3
```
This is a plaintext code snippet.
```
Specifying Language inside code block
Using ```{language} ``` you will get a code block with syntax highlight:
1
2
3
4
5
6
7
8
9
10
11
```python
print("hello")
```
```yaml
key: value
```
```shell
ls -al ,or any text you like
```
use ````markdown to wrape the code blocks to display the raw blocks itself
The above are code blocks produces similar output as below
1
2
print("hello")
remove Line Number inside code block
By default, all languages except plaintext, console, and terminal will display line numbers. When you want to hide the line number of a code block, add the class nolineno to it:
1
2
3
4
```shell
echo 'No more line numbers!'
```
{: .nolineno }
Specifying the Filename or text in code block
You may have noticed that the code language will be displayed at the top of the code block. If you want to replace it with the file name, you can add the attribute file to achieve this:
1
2
3
4
```shell
# content
```
{: file="path/to/file" }
output:
1
# content
Liquid Codes
In Chirpy, which is built on Jekyll, Liquid code refers to the use of the Liquid templating language, used to process dynamic content inside .html, .md, and .yml files.
It uses a syntax like:
1
2
3
4
5
{{ variable }} → output content
{% tag %} → logic or commands (e.g., if, for, include)
{% if page.author %}
Author: {{ page.author }}
{% endif %}
If you want to display the Liquid snippet, surround the liquid code with and:
1
2
3
4
5
6
7
```liquid
{% if product.title contains 'Pack' %}
This product's title contains the word Pack.
{% endif %}
```
Creating Expand/Collapse Sections with Markdown
You can use the <details> and <summary> tags to create expandable sections.
If want to renderd markdown formats like list ,codeblocks etc use the
<div>or<article>tags inside<summary>to wrape the content. all examples shown below.
Normal text Expand/Collapse syntax
1
2
3
4
5
<details>
<summary>Click to expand plain summary</summary>
This is a normal summary to create expandable blocks
if doesnot supports markdown special formats like list or code blocks
</details>
Example
Click to expand plain summary
This is a normal summary to create expandable blocks if doesnot supports markdown special formats like list or code blocksExpand/Collapse syntax with markdown formatting
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<details>
<summary>Click to expand markdown formatting</summary>
<div markdown="1">
- List item 1
- List item 2
```python
print("Hello, world!")
```
</div>
</details>
Example
Click to expand markdown formatting
- List item 1
- List item 2
1
print("Hello, world!")
- Note:
<div markdown="1">can be replaced with<article markdown="1">as well- You can put Expand/Collapse block at any level and can make it a part of a list as well
Attribute Lists
You can add attributes like CSS classes, IDs, or data- attributes to elements using {}:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
## This Won’t Show in the TOC
{: data-toc-skip="" .mt-4 .mb-0 }
# H1 — heading
{: .mt-4 .mb-0 }
## H2 — heading
{: data-toc-skip='' .mt-4 .mb-0 }
### H3 — heading
{: data-toc-skip='' .mt-4 .mb-0 }
#### H4 — heading
{: data-toc-skip='' .mt-4 }
| Attribute | Effect |
|---|---|
data-toc-skip | (optional) Skips this heading from the sidebar TOC |
.mt-4 | (optional) Adds top margin (Chirpy spacing class) |
.mb-0 | (optional) Removes bottom margin |
Highlight Blocks or prompt boxes (Chirpy-Specific)
Chirpy supports custom prompt boxes using Kramdown attribute classes .These are custome defined.
note here and char > (blockquote) is nedded for the .prompt-* to work
Chirpy does support blockquotes styled as prompts by using the prompt-{type} CSS class—specifically for
tip, info, warning, anddanger
1
2
3
4
5
6
7
8
9
10
11
12
> **info** This is a info remember
{: .prompt-info }
> **Tip:** Always use version control!
{: .prompt-tip }
> **Warning:** Don’t push secrets to GitHub.
{: .prompt-warning }
> **Danger:** This will delete all your data.
{: .prompt-danger }
The above are translated in to:
info This is a info remember
Tip: Always use version control!
Warning: Don’t push secrets to GitHub.
Danger: This will delete all your data.
Lists
Ordered list
1
2
3
4
1. Firstly
2. Secondly
3. Thirdly
- Firstly
- Secondly
- Thirdly
Unordered list
1
2
3
- Chapter
- Section
- Paragraph
- Chapter
- Section
- Paragraph
- Section
ToDo list
1
2
3
4
- [ ] Job
- [x] Step 1
- [x] Step 2
- [ ] Step 3
- Job
- Step 1
- Step 2
- Step 3
Description list
1
2
3
4
5
Sun
: the star around which the earth orbits
Moon
: the natural satellite of the earth, visible by reflected light from the sun
Using <kbd> keyboard style key
1
2
<kbd>here is my key</kbd> > <kbd>another key</kbd>
<kbd>Ctrl</kbd> + <kbd>c</kbd>
output :
here is my key > another key
Ctrl + c
Working with Images
For working with image covers click here
Images in Chirpy can be embedded using standard Markdown syntax, but Chirpy also provides additional CSS utility classes and attributes to fine-tune how images are displayed.
These can be applied using attribute lists {} directly after the image syntax. like {: width="972" height="589" .w-75 .normal }
Basic Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{: width="972" height="589" .w-75 .normal }
### Default (with caption)
{: width="972" height="589" }
_Full screen width and center alignment this is caption_
### Left aligned
{: width="972" height="589" .w-75 .normal}
### Float to left
{: width="972" height="589" .w-50 .left}
### Float to right
{: width="972" height="589" .w-50 .right}
Parts Explained
| Part | Meaning |
|---|---|
width="972" | Sets the explicit width of the image in pixels |
height="589" | Sets the explicit height of the image in pixels |
.w-50 | Applies Chirpy’s utility class to set width to 50% of container |
.left | Floats the image left using Chirpy’s utility class |
Default (with caption)
1
2
{: width="972" height="589" }
full captino
Full screen width and center alignment this is caption
Left aligned
{: width="972" height="589" .w-75 .normal} 
Float to left
{: width="972" height="589" .w-50 .left}
This helps the image float to the left side while allowing text to wrap around it, creating visually engaging layouts.
For example:
- Place diagrams, charts, or screenshots on one side
- Perfect for tutorials and documentation
Chirpy’s utility classes like .left and .w-50:
- Control alignment and sizing easily
- Remove the need for custom CSS
- Keep content clean and user-friendly
This improves readability and makes posts more polished using simple Markdown and Chirpy’s utilities.
Float to right
{: width="972" height="589" .w-50 .right}
This helps the image float to the right side while allowing text to wrap around it, creating a balanced and dynamic layout. You can mix paragraphs and bullet points seamlessly around floated images to enhance clarity and flow. This improves readability and makes posts more polished using simple Markdown and Chirpy’s utilities.
For example:
- Place diagrams, charts, or screenshots on one side
- Perfect for tutorials and documentation
Chirpy’s utility classes like .right and .w-50:
- Control alignment and sizing easily
- Remove the need for custom CSS
- Keep content clean and user-friendly
Adding Videos
There are predefined layouts for rendering video files which are present in the _includes/embed/ in the core-theme we can use those to render videos from social media and
| File / Folder | Purpose |
|---|---|
_includes/embed/youtube.html | Embeds YouTube videos using their video ID |
_includes/embed/twitch.html | Embeds Twitch videos using their video ID |
_includes/embed/bilibili.html | Embeds Bilibili videos using their video ID |
_includes/embed/video.html | Embeds self-hosted video files with advanced options |
_includes/embed/audio.html | Embeds audio files (e.g., MP3) with metadata support |
Social Media Platform
You can embed videos from social media platforms with the following syntax:
1
{% include embed/{Platform}.html id='{ID}' %}
Where Platform is the lowercase of the platform name, and ID is the video ID.
The following table shows how to get the two parameters we need in a given video URL, and you can also know the currently supported video platforms.
| Video URL | Platform | ID |
|---|---|---|
| https://www.youtube.com/watch?v=H-B46URT4mg | youtube | H-B46URT4mg |
| https://www.twitch.tv/videos/1634779211 | twitch | 1634779211 |
| https://www.bilibili.com/video/BV1Q44y1B7Wf | bilibili | BV1Q44y1B7Wf |
Video Files
If you want to embed a video file directly, use the following syntax:
1
{% include embed/video.html src='{URL}' %}
Where URL is a URL to a video file e.g. /path/to/sample/video.mp4.
You can also specify additional attributes for the embedded video file. Here is a full list of attributes allowed.
poster='/path/to/poster.png'— poster image for a video that is shown while video is downloadingtitle='Text'— title for a video that appears below the video and looks same as for imagesautoplay=true— video automatically begins to play back as soon as it canloop=true— automatically seek back to the start upon reaching the end of the videomuted=true— audio will be initially silencedtypes— specify the extensions of additional video formats separated by|. Ensure these files exist in the same directory as your primary video file.
Consider an example using all of the above:
1
2
3
4
5
6
7
8
9
10
{%
include embed/video.html
src='/path/to/video.mp4'
types='ogg|mov'
poster='poster.png'
title='Demo video'
autoplay=true
loop=true
muted=true
%}
Audios
there is a predefined audio template that renders ours audio
| File / Folder | Purpose |
|---|---|
_includes/embed/audio.html | Embeds audio files (e.g., MP3) with metadata support |
If you want to embed an audio file directly, use the following syntax:
1
{% include embed/audio.html src='{URL}' %}
Where URL is a URL to an audio file e.g. /path/to/audio.mp3.
You can also specify additional attributes for the embedded audio file. Here is a full list of attributes allowed.
title='Text'— title for an audio that appears below the audio and looks same as for imagestypes— specify the extensions of additional audio formats separated by|. Ensure these files exist in the same directory as your primary audio file.
Consider an example using all of the above:
1
2
3
4
5
6
{%
include embed/audio.html
src='/path/to/audio.mp3'
types='ogg|wav|aac'
title='Demo audio'
%}
Linking url and sections in Jekyll
Linking sections in same file
1
[any text name to show](#section-name-separated-by-hypen-all-in-small)
or any special name is forced ::- check – Bonus: Manually add a custom anchor
Linking sections and url dynamically from other files
1
2
3
4
5
6
7
8
9
# POST URL (different)
[any name you like]({{ site.posts | where: "slug", "typing-in-python" | first.url | relative_url }}) # {{}} <-- this is a liquid language used by jekyll templeting engine
# POST URL SECTIONS (different)
[Go to Installation]({{ site.posts | where: "slug", "my-post" | first.url | relative_url }}#installation)
# Can also be done directly via href in html tags inside the Md file (Here target is for opening in new tab)
<a href="{{ site.posts | where: "slug", "openTelemetry-unified-observability-part1" | first.url | relative_url }}" target = "_blank">OpenTelemetry part 2</a>
Note : you can force a
slugto the front matter like this
1 2 3 4 --- title: My Post slug: my-post ---
Breakdown of Each Part (Additional Explanation)
|is called a filter pipe It takes the output of the left-hand side and passes it through a filter on the right-hand side. just like unix pipe
site.posts
Built-in Jekyll variable containing all posts in_posts/.- 🔹 Example:
1 2 3 4
[ { "title": "Post A", "slug": "post-a", "url": "/blog/2023/06/01/post-a/" }, { "title": "Post B", "slug": "chirpy-jekyll-front-matter", "url": "/blog/2023/06/25/chirpy-jekyll-front-matter/" } ]
- 🔹 Example:
| where: "slug", "chirpy-jekyll-front-matter"
Filters posts byslugvalue.- 🔹 Result:
1 2 3
[ { "title": "...", "slug": "chirpy-jekyll-front-matter", "url": "/blog/2023/06/25/chirpy-jekyll-front-matter/" } ]
- 🔹 Result:
| first
Gets the first (and likely only) matching post..url
Extracts the URL of that post.- 🔹 Example:
/blog/2023/06/25/chirpy-jekyll-front-matter/
- 🔹 Example:
| relative_url
Prependsbaseurlif set in_config.yml.
🧾 Final Output Example With:
- A post slug:
chirpy-jekyll-front-matter baseurl: ""
This line:
1
/posts/chirpy-jekyll-front-matter/
➡️ renders as:
/blog/2023/06/25/chirpy-jekyll-front-matter/
Linking direct urls
1
[any name like click me](https://www.myurl.com)
Bonus: Manually add a custom anchor
weird heading
Note you can anchor all the headings exactly the same way. This applies to headings of any level —
#,##,###, etc.When you write this in Markdown# Some HeadingJekyll (via Kramdown) automatically turns it into<h1 id="some-heading">Some Heading</h1>,the tag<h1>or<h2>etc depends on the level
If your heading is like ## Step 1: Setup 🚀: It might produce a messy ID. So you can force an ID like this ## Step 1: Setup 🚀 {#setup}:
examples::
1
## Step 1: Setup 🚀 {#setup}
Then link to:
1
[some name](#setup)
Linking to a Non-Heading
You’ll need to manually insert an HTML ID like:
1
2
3
4
5
6
<span id="my-anchor"></span>
Some **custom** section here.
Then link with:
[Jump here](#my-anchor)
Please follow the link to learn more about writing a blog from the official site:
Write a New Post – Chirpy Official Guide
Inspiration
The Chirpy theme has been an incredible foundation for building this blog. Huge appreciation to Cotes and the open-source contributors behind Chirpy for their continuous work on making Jekyll blogging modern, minimal, and developer-friendly.
My blog setup, layout decisions, and customizations were strongly influenced by their excellent documentation and examples, including:
Thanks to their efforts, creating a beautiful and functional static blog has never been easier.
