sphinx-jekyll-builder

sphinx builder that outputs jekyll compatible markdown files with frontmatter

Please ★ this repo if you found it useful ★ ★ ★

Features

• Generates markdown
• Supports frontmatter
• Compatible with jekyll
• Compatible with gatsby

Installation

pip install sphinx-jekyll-builder

Dependencies

• Python 3 (3.10 or newer)
• Sphinx 7.x or newer

Usage

Load extension in configuration.

conf.py

extensions = [
    'sphinx_jekyll_builder'
]

Build jekyll files with the sphinx-build command

cd docs
sphinx-build -M jekyll ./ build

The generated markdown lands in build/jekyll/. Every file starts with a YAML frontmatter block:

---
date: '2026-08-12T17:30:40.529Z'
docname: guide/gettingStarted
images: []
path: /guide-getting-started
title: Getting Started
---

# Getting Started

variable	description
date	build timestamp (ISO 8601, JavaScript compatible)
docname	the sphinx docname
images	images referenced by the document
path	kebab-case permalink derived from the docname
title	the document title (falls back to the docname)

A ready-to-build sample project lives in examples/basic.

Development

make prepare  # one-time machine setup (asdf toolchain + uv sync)
make build    # build sdist + wheel into dist/
make test     # unit tests with coverage
make test/e2e # build the example project through the sphinx-build CLI
make format   # black
make lint     # black --check + basedpyright

Support

Submit an issue

Contributing

Review the guidelines for contributing

License

MIT License

Clay Risser © 2018 - 2026

Changelog

Review the changelog

Credits

• Clay Risser - Author
• Matthew Brett - doctree2md
• Liran Funaro - sphinx-markdown-builder