gh-pages publishing

[rvagg]

Sitting on top of #216 so most of the changes to schemas/ aren't relevant (there are some minor changes dealing with <pre> tags).

This does two things, found in the two commits at the head of this branch:

• Use Vuepress for compiling a static site. You can now npm install && npm run build here to generate a static site (which ends up in html/.vuepress/dist). (fwiw I started playing with Hugo cause that's what others in PL are using but the yak shaving was too much, vuewpress is actually really nice, and quite comfortable for a JS-native).
• Use GitHub Actions to publish that static content to the gh-pages branch. This'll need a deploy key and a secret key set in this repo's settings for it to work.

For now the root, /specs/ has a simple index that says what this is just points to /specs/schemas/, thats in .vuepress/README.md. It manually copies in the /schemas/ directory before compiling so the other spec docs are ignored but we could add them in over time and expand this.

It adds syntax highlighting to ipldsch code blocks, which is really nice to look at.

"Edit this page on GitHub" is on most pages and jumps you straight into the GitHub editing window.

I had to add a hack for .ipldsch and .json files: during the build step they get converted to .md files with code fences around them, so they render nicely. But that means rewriting links that point to them and also makes the "Edit this page on GitHub" too difficult for them.

Preview available at: https://rvagg.github.io/specs/

[rvagg]

#216 merged, this should be easier to review now, only 2 commits

[vmx]

I prefer local paths over absolute paths for static websites, so that you can easily run them locally (often you even won't need a webserver). I don't know if that's possible with vuepress. I at least couldn't get it work locally (I also tried starting an http server within html/.vuepress/dist).

[mikeal]

go ahead and add a CNAME file for specs.ipld.io, should work https://github.com/protocol/infra/issues/503

[rvagg]

@vmx yeah, I'd much prefer relative URLs too for the flexibility but vuepress doesn't allow this as far as I can make out. I meant to add a serve target so I've done that now in the latest addition, npm run serve and you'll get a web server running to view the pages.

[rvagg]

Following the rabbit hole through vuejs/vuepress#796 and on to various other issues in vue itself and html-webpack-plugin, it looks like (a) it's currently impossible to do relative URLs and (b) it might be possible in the not too distant future once dependency updates flow down. There's a change in vue that hasn't been published that should help a lot. So long-term, we should make this portable. Short-term let's just make it work and get it up.

For now, npm run serve.

I've added a CNAME file with specs.ipld.io and changed the publish base to /

I've also added another change that replaces all of the ../ URLs in /schemas/ docs to absolute URLs back to this repo. Since we are only publishing /schemas/ for now, those don't work on the web. It can be undone when we publish more stuff.

[vmx]

Thanks, now it works locally. That surely is good enough, I just wanted some easy way to view it locally.