Thanks for the ideas @chuckhoupt and @MichaelCurrin!
I am indeed in a Github Pages environment. I was under the impression that
_site isn’t something I can modify at all under Pages, and testing @chuckhoupt’s idea seems to confirm this -
keep_files: [docs] works when testing with
jekyll s locally, but not when pushed to Github. Does Pages use a different destination directory that I’m not aware of, or is it just impossible to use
keep_files with Pages?
@MichaelCurrin My site is a hybrid - mostly Jekyll-processed files, with only one subdirectory that contains purely tool-generated HTML/CSS/etc. I can’t use
.nojekyll because that trick seems to only apply to the entire repo, not just subdirectories. Your suggestion of manually
cping the docs into
_site doesn’t work with Github Pages, since I can’t customize the build process for Pages deployments.
I have come up with something of a solution, however: Since I’m using Github Actions to generate everything in the
docs directory and commit to the
gh-pages branch automatically, I’ve added a step to that build process that lists all the newly-generated files whose names start with underscores, and adds them to
_config.yml individually. It’s a bit of a hack, but it works something like this:
# Working directory is the root of the Pages site
# Generate documentation in the `docs` subdirectory of the site
npx typedoc ../project-source/index.ts --out docs --readme none
# Add all generated files that start with underscores to `include`
for file in "$UNDERSCORE_FILES[@]"
# This line assumes that `includes` is at the end of the config
echo "- '$file'" >> _config.yml
This is just a rough example. My actual use case is building docs for new tags into dedicated subdirectories - e.g. a new tag
v2.3.0 would generate docs for that version of the project and push them to the
docs/v2.3.0 directory. Because this doesn’t involve overwriting old versions, I don’t have to worry about diplucate entries in the
includes list, but a more robust solution might be to use a proper YAML utility to rewrite the config.
Anyway, I think I’m gonna submit a feature request on the Jekyll repo for supporting glob patterns in
includes and similar config options - it seems to me like that would make automated use cases significantly simpler, especially when working with Github Actions and Pages together.