Sometimes you need something in your Jekyll site that should not go through Jekyll’s build at all: a documentation folder generated by a different tool, a set of static HTML pages, a small app bundled somewhere in your repo. Jekyll has a straightforward way to serve that content alongside your generated pages, and it is worth being precise about what that method does and does not give you.

Say you want to host a documentation folder at /documentation that uses its own HTML, independent of your Jekyll-generated pages.

1. Place your static HTML files in the right folder

/documentation/index.html
/documentation/page1.html
/documentation/page2.html

2. Tell Jekyll to leave the folder alone

By default, Jekyll processes every file it finds in the project. To stop it from touching /documentation, add an exclude rule in _config.yml:

exclude:
  - documentation

Jekyll will now ignore that folder entirely during the build.

3. The folder still gets served

Jekyll serves static files from any folder in the project root except the ones you have excluded, so /documentation will still be publicly reachable at /documentation/ once the site builds. Excluding a folder from processing is not the same as excluding it from the output.

4. Know what “excluded” actually means for shared layout

This is the part that is easy to get wrong: because Jekyll never touches an excluded folder, Liquid tags like {% include head.html %} will not render inside those files. Jekyll is not processing them, so there is nothing there to expand the include. If you want the documentation pages to share your site’s header, footer, or styles, exclude is the wrong tool.

For that case, keep the files out of the exclude list and give each one front matter instead, even if it is just two empty dashes:

---
---
<!-- your HTML here -->

Front matter tells Jekyll to process the file, so it can now use layout:, {% include %}, and anything else in your Jekyll template system, while still living outside your normal _posts or page structure. You lose the completely-untouched guarantee, but you gain the ability to actually share layout with the rest of the site, which is usually the point of wanting shared styling in the first place.

5. Consider a plugin only if you need automation

jekyll-static exists to automate this exclude-and-serve pattern instead of managing it by hand in _config.yml. For a folder or two, the manual exclude rule above is simpler and has one less dependency to track. Reach for the plugin once you are managing enough non-Jekyll folders that the manual list itself becomes a maintenance burden, and check first whether your host allows it: GitHub Pages, for instance, only allows a fixed list of plugins, so this route will not work there without a custom build step.

The choice comes down to what you actually need: fully untouched static files that Jekyll never sees, or files that render inside your site’s existing layout. Exclude gives you the first. Front matter gives you the second. They are not interchangeable, and putting a folder in the wrong one of the two is the most common way this setup breaks.