PDF to Markdown for Jekyll: Turn PDFs into Blog Posts
Jekyll powers GitHub Pages and a lot of long-running technical blogs. Its conventions for posts (<code>_posts/YYYY-MM-DD-title.md</code>) and front matter are simple but rigid: converting a PDF into a publishable Jekyll post is mostly about getting the filename and front matter right.
Jekyll post conventions
Posts live in _posts/, named YYYY-MM-DD-slug.md. The date in the filename and the date: front matter field both matter: Jekyll won't publish a post dated in the future unless you pass --future. Required front matter: title, date, layout (usually post). Optional but useful: categories, tags, permalink.
Liquid templating gotchas
Jekyll runs Markdown through the Liquid templating engine before rendering. That means {{ }} and {% %} in your converted content will be interpreted as Liquid syntax, which usually isn't what you want. If your PDF source contains those sequences (in code samples, for instance), wrap them in {% raw %} ... {% endraw %} after conversion to disable Liquid processing.
Frequently asked questions
How do I name files for the _posts directory?
YYYY-MM-DD-slug.md. The date prefix is required: Jekyll uses it to determine publication order and won't publish posts dated in the future without explicit override. The slug becomes part of the URL.
What front matter does Jekyll require?
Minimum: title, date, and layout: post. Common additions: categories, tags, permalink, excerpt, author. Anything else is accessible in templates as page.fieldname.
How do I handle Liquid template tags in converted content?
Wrap any literal {{ }} or {% %} sequences in {% raw %} ... {% endraw %} after conversion. This is most often needed when your source PDF contained code samples that happen to use those syntax patterns.
Can I use Jekyll collections for converted PDFs?
Yes: define a collection in _config.yml (e.g. papers:), put converted Markdown files in _papers/, and they become accessible as site.papers in templates. Useful when you want a separate output structure from blog posts.
Will my converted Markdown work on GitHub Pages?
Yes: GitHub Pages runs Jekyll natively. As long as the front matter is valid and the filename follows convention, push to the repo and the post is live within minutes. Standard Markdown features all render correctly with the default Minima theme.