Combining Markdown and HTML in Jekyll

This document explains how to embed markdown content within HTML pages in Jekyll. The examples shown in the about.html and projects.html files demonstrate various techniques.

Prerequisites

Your HTML file must have Jekyll front matter at the top to be processed by Jekyll:

---
layout: default
title: Your Page Title
permalink: /your-page-url
---

Techniques for Embedding Markdown

1. Direct Markdown Content

The simplest approach is to write markdown directly in your HTML file:

## My Section Title
This is **bold text** and this is *italic text*.

- List item 1
- List item 2

2. Using the `capture` and `markdownify` Filters

Capture markdown content in a variable and convert it to HTML:

<div class="my-section">

<h3 id="dynamic-content">Dynamic Content</h3>
<p>This markdown content can include <strong>variables</strong> and be processed dynamically.</p>

<p>Current date: July 18, 2025</p>

</div>

3. Processing Liquid Variables as Markdown

You can create markdown content using Liquid variables:


<p>This is <strong>bold</strong> and this is <em>italic</em></p>

4. Including Markdown Files

Include content from other markdown files:


**Note:** The include path should be relative to your current file location.

### 5. Processing Data with Markdown

Loop through data and apply markdown formatting:

```liquid

  
  <p><strong>Open Broadway Data:</strong> Open Broadway Data is an open data platform which aims to collect, display, and analyze data from all Broadway shows since 1738.</p>


  
  <p><strong>Glonky Animals:</strong> A simple, silly mobile game for toddlers featuring adorable animals with fun sounds and animations. Perfect for ages 2+</p>


  
  <p><strong>Artists Who Code:</strong> A community and mentorship organization for artists who have (or are working toward) a career in the tech industry.</p>


  
  <p><strong>Data Engineer Things:</strong> Editor in Chief of Data Engineer Things (DET), Medium publication.</p>


  
  <p><strong>Pydantic<br />Open Source Contributor:</strong> Open source contributor to Pydantic.</p>


  
  <p><strong>Stack Overflow<br />Top 1% Contributor:</strong> Top 1% Overall contributor.</p>

6. Complex HTML Structure with Embedded Markdown

Combine HTML structure with markdown content:

<div class="card">
  <div class="header">
    <h2></h2>
  </div>
  <div class="content">
    
    
<p><strong>Features:</strong></p>
<ul>
  <li>Feature 1</li>
  <li>Feature 2</li>
</ul>


  </div>
</div>

Important Notes

File Extension: You can use either .html or .md extensions. Jekyll will process both if they have front matter.
Markdown Parser: Jekyll uses Kramdown by default. You can configure this in _config.yml:
```
markdown: kramdown
kramdown:
  input: GFM
  hard_wrap: false
```
HTML in Markdown: You can also embed HTML within markdown files for more complex styling.
Performance: The markdownify filter processes content at build time, so there’s no runtime performance impact.

Examples in This Site

about.html: Shows direct markdown, capture/markdownify, and variable processing
projects.html: Demonstrates complex HTML structures with embedded markdown and data processing

Styling

The markdown content will be styled according to your site’s CSS. Make sure your CSS handles the generated HTML elements (h1-h6, p, ul, ol, strong, em, etc.).

Yaakov Bressler