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 cp
ing 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 include
in _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`
UNDERSCORE_FILES=(docs/**/_*)
for file in "$UNDERSCORE_FILES[@]"
do
# This line assumes that `includes` is at the end of the config
echo "- '$file'" >> _config.yml
done
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.