Linking to your Javascript Library from Inside the Github Pages Docs Folder

I maintain a javascript library, and the docs are inside a \docs folder, which is served by Github pages (a new-ish feature from Github). It’s convenient having everything in one repo. My favorite part? I can update the docs in the same commit that new features are added. This is especially great when other people submit PRs because I can ask them to add documentation for the feature they are submitting.

The only remaining bit of workflow is to copy a version of my library into my docs folder each time I create a new version (so the examples in the docs are always running on the newest version).

So then I started wondering: Is there a way to avoid needing to copy this file every time?

As far as I could tell, my options were:

1. Add an npm task to copy the file. Maybe I could chain this onto another task I run regularly, like the minification task.
2. Find a way to directly link to the file in the root folder from inside the docs.

I was intrigued by the zero-overhead of option 2, so I set up a test file with the following approaches:

• Use a relative link going up a directory
• Use a symlink, that links up a directory
• Link to a CDNed version of the library on master, using raw-git

So here’s what I found:

• Relative link: 404s
• Symlink: Breaks the github-pages build (they sent me a notification email with error information in it)
• Raw-git link: Works

So at least one of them worked, right? Well the more I thought about the raw-git option, the more flaws I found. For example, the library in my docs isn’t going to be fully updated during local development, and that could be an issue if I’m working on a major update locally.

In the end, I decided to go with option 1 (an NPM task that copies it over). If anybody has better ideas on how to make option 2 work, let me know in the comments.