Home › Guides › Jekyll or plain HTML
GitHub Pages with Jekyll or plain HTML: which should you choose?
GitHub Pages serves finished HTML files, and there are two ways to produce them: let Jekyll assemble the pages from Markdown and templates, or write the HTML yourself, by hand or with your own build script. Gerris runs both. hillmole.com, Chris Abraham's serialized novel, is a Jekyll site with 309 entries moved from Movable Type in October 2026. gerris.ai, christopherabraham.com, gerriscorp.com, chrisabraham.net, and thechrisabrahamshow.com are plain HTML. Chris built every one of them and maintains them all, which settles the first question people ask: the work is the same either way—writing and editing text files, then publishing. The choice depends on the site.
What does Jekyll do on GitHub Pages?
Jekyll is a static site generator, and GitHub runs it on every Pages site published from a branch unless you tell it not to. You write each page or post as Markdown with a block of YAML front matter at the top: title, date, layout, and any other values. Jekyll pours that content into layouts written in Liquid, its templating language, and writes the finished HTML. A _config.yml file holds the site's settings, including front matter defaults: a rule that every file of one type, in one path, gets the same values unless the file says otherwise.
GitHub's build runs Jekyll 3.10 through the github-pages gem, with a fixed list of supported plugins. That list includes jekyll-feed, jekyll-sitemap, jekyll-seo-tag, and jekyll-redirect-from, and GitHub Pages will not run a plugin outside it. A site that needs anything else builds through a custom GitHub Actions workflow, which can deploy the output of any static site generator.
What is a plain HTML site on GitHub Pages?
A plain HTML site is the finished pages committed to the repository, with a file named .nojekyll in the root so GitHub publishes them untouched. GitHub added that file in 2009 for sites whose files or folders start with an underscore, which Jekyll otherwise treats as its own and leaves out. The pages can be written by hand, as on gerris.ai, or generated by a script you control. christopherabraham.com and gerriscorp.com are built by a Python script that writes every page, the sitemap, the feeds, and llms.txt from source files, and refuses to finish if a title runs long or two pages repeat each other. thechrisabrahamshow.com rebuilds itself every morning from its podcast feed, in a scheduled GitHub Actions job.
What is each approach good at?
- Jekyll suits a site that grows by adding writing: a blog, a serialized book, an archive, documentation. A new post is one Markdown file, and a change to one layout changes every page. It also handles a migration well. Hill Mole's Movable Type archive pages became a Jekyll collection, and one front matter default keeps every one of them out of the sitemap and marked noindex while their old URLs still answer.
- Plain HTML suits a site where every page is deliberate: a business site, a service catalog, a set of guides. Nothing is assembled at request time or at GitHub's build, so what is in the repository is exactly what visitors and crawlers receive. A custom build script can enforce rules Jekyll has no plugin for, such as unique titles, length limits on descriptions, and a check against phrasing borrowed from a sibling site.
How do they compare?
| Question | Jekyll on GitHub Pages | Plain HTML |
|---|---|---|
| Where pages are built | GitHub's build, from Markdown and Liquid layouts | Your own editor, script, or workflow |
| Adding a page | One Markdown file with front matter | One finished page, or one source file your script expands |
| Changing every page | Edit one layout | Edit the template in your script, or every file by hand |
| Plugins and extensions | GitHub's supported list only, unless you build with Actions | Anything your own build can do |
| Files starting with an underscore | Skipped unless included in _config.yml | Published as they are, with .nojekyll |
| Builds per hour | A soft limit of 10 on GitHub's build | No limit when published through your own Actions workflow |
The rest of GitHub's limits are the same either way: a published site no larger than 1 GB, a soft bandwidth limit of 100 GB a month, and deployments that time out after 10 minutes.
How does the work compare in practice?
Working in either kind of repository means following its conventions. In a Jekyll site the conventions are fixed and public: where layouts live, what front matter means, which plugins exist. In a plain HTML site with a build script, the conventions are whatever the script enforces, and the script's checks become the checklist every change is run against. Either way the work is writing text files and running a build. Hill Mole's move from Movable Type to Jekyll and the plain HTML builds of the other five sites are all Chris's own work, and he decides what each site says.
The difference that matters is where the rules live. Jekyll carries its rules in the framework, so anyone who picks up the repository already knows most of them. A custom build carries its rules in the script and a written briefing, so the briefing has to be kept current, or the next round of changes will quietly undo the last one's work.
Which should you choose?
Choose Jekyll when the site is mostly writing that keeps arriving, when you want to add pages in Markdown without touching HTML, or when you are moving a blog off a platform such as Movable Type or WordPress and need its old URLs kept. Choose plain HTML when the site is a fixed set of pages that must each say something exact, when you want a build that checks every page before it publishes, or when the site has to pass through no processing at all. For AI search, both publish the same thing a crawler reads, and the work that earns citations is the same: clear titles, structured data, a sitemap, an llms.txt, and pages that answer questions directly.
One limit applies to both. GitHub's terms say Pages is not intended or allowed for running an online business, an e-commerce site, or any site primarily directed at commercial transactions, and it should never carry passwords or card numbers. A brochure site, a practice, a portfolio, a book, or a publication fits. A store with a checkout belongs on a platform built for it.
Frequently asked questions
Does GitHub Pages use Jekyll by default?
Yes, for a site published from a branch. GitHub runs its own Jekyll build on the repository unless a file named .nojekyll sits in the root, or the site is published through a custom GitHub Actions workflow.
What does a .nojekyll file do?
It tells GitHub Pages to skip Jekyll and publish the files exactly as they are. GitHub added it in 2009 for sites whose files or folders start with an underscore, which Jekyll treats as its own and does not copy.
What skills does each approach take?
Jekyll takes Markdown and YAML front matter for the pages, with the layouts written once in Liquid and reused. Plain HTML takes HTML itself, page by page, or a build script you write and maintain. Gerris runs one Jekyll site and five plain HTML sites, all built and kept by Chris, and the working skills are the same in both: writing clean text files, keeping titles and descriptions honest, and checking the output before it publishes.
Which is better for SEO, Jekyll or plain HTML?
Neither, by itself. Both publish finished HTML that every crawler reads. What decides search and AI visibility is what the build puts in the pages: titles, descriptions, schema, sitemaps, and what it refuses to publish.
Can I run an online store on GitHub Pages?
No. GitHub's terms say Pages is not intended or allowed for running an online business or an e-commerce site, or for sending passwords or card numbers. Brochure sites, guides, portfolios, and archives fit; checkouts belong on a platform built for them.
Read next: GitHub Pages websites built by Gerris, and the AI search glossary for the terms that decide what an answer engine does with the pages.