问题

I'm developing application that uses D3.js to showing some visualizations. How can I show preview of HTML file (that uses JS) on GitHub? I need demo for every commits (historical), not only for latest version.

^{I generate static version of my application to HTML+JS with bundled JSON data and linked D3.js library from CDN, so I need only to serve HTML+JS. No backend.}

GitHub Pages

My first thought is using GitHub Pages ^{(it's popular answers #1, #2)}. It is good, but with this I can show demo only for latest version (latest commit if I set gh-pages for docs directory on master branch) or only for one specific version (if I set gh-pages for gh-pages branch and push some version to it).

I need to show demo (preview HTML) for all commits in repo. I would like to be able to see demo with previous version of application (preview previous commits).

Generate image (screenshot)

I can do screenshot of running D3.js application and attach image to repo and show in README.md. When somebody open previous commit he will see previous version of application. This is what I want.

But with static image I lose advantage of D3.js. My application is dynamic (you can zoom, click on charts, select data to show, show tooltips etc.).

HtmlPreview or RawGit

I found ^{(#1, #2)} services that can serve HTML file directly from GitHub:

https://htmlpreview.github.io/
https://rawgit.com/

With this I can link to specific file (even to specific version of file! That's it!) and proxy by HTMLPreview/RawGit to show preview.

But I have two problems with this:

1. Author of RawGit says that I shouldn't use this tool for creating public demos (what I just wanted to do!):

Don't use development URLs in example code or in public demos, because people often copy and paste that code and use it in production apps without realizing that they need to change the URLs. Then they send too much traffic to RawGit, get throttled, and their apps break.

(I guess that the same can applies to HtmlPreview.)

2. How to dynamically link to file in this commit? (I want to write link for demo in README.md.)

When I create links like this:

https://rawgit.com/mkczyk/test-experiment/master/index.html
https://htmlpreview.github.io/?https://github.com/mkczyk/test-experiment/blob/master/index.html

It will be links to latest version (when somebody enter into old commit he will see demo for newest version instead of specific version).

So I have to create link with SHA, like this:

https://rawgit.com/mkczyk/test-experiment/d7a4c7953d2b9084ca520eeb4434dd6d6689880d/index.html
https://htmlpreview.github.io/?https://github.com/mkczyk/test-experiment/blob/d7a4c7953d2b9084ca520eeb4434dd6d6689880d/index.html

But how do I know what SHA will be generated before I create commit? I want to create commit and write link on README.md in the same commit.

(I tried to create commit locally, read generated SHA, change README.md to write link and git commit --amend, but SHA is changed after amend.)

Is there any way to create dynamic link on GitHub? Maybe some GitHub variable (<sha-of-this-commit>) which would be dynamically changed by GitHub when generates README.md?

I know I can link relative:

[index.html](index.html)

And GitHub replace this with:

https://github.com/mkczyk/test-experiment/blob/d7a4c7953d2b9084ca520eeb4434dd6d6689880d/index.html

But I don't know how to concatenate this with RawGit or HTMLPreview.

Jupyter Notebook

I found this demo: https://github.com/soxofaan/jupyter-playground/tree/master/jupyter-custom-d3-visualization

I see that I can embed JS and D3.js script in Jupyter Notebook (.ipynb).

GitHub supports as default a preview of Jupyter Notebooks. But as you can see it doesn't support embed JavaScript result: https://github.com/soxofaan/jupyter-playground/blob/master/jupyter-custom-d3-visualization/jupyter-custom-d3-visualization.ipynb

<IPython.core.display.Javascript object>

There is workaround and using nbviewer to preview JS: https://nbviewer.jupyter.org/github/soxofaan/jupyter-playground/blob/master/jupyter-custom-d3-visualization/jupyter-custom-d3-visualization.ipynb

It works the same as RawGit or HTMLPreview but for Jupyter Notebook.

And with this I have the same problem as above. I cant make link to specific commit (I don't know what SHA will be generated before I create commit).

This also has a drawback that you have to create entire Jupyter Notebook only for embed JS.

ObservableHQ is more comfortable for D3.js. But GitHub doesn't support it. That would be perfect if I could write observablehq-notebook, commit code to GitHub and it will render preview.

Cumbersome workarounds

Giving up with demo for historical commits... But this is my question how to deal with it.
Using external service (eg. JSFiddle, Codepen or mentioned before ObservableHQ) and creating independent demo for each change and paste link before committing. But this has many drawbacks:

A lot of entries in external service. When I make mistake or forgot that I need this and delete old entry my demos in old commits in repo will be broken (and no way to recovery this because id of enty will be changes - only way is to rewrite all commits in repo!).
There is no single source of truth (my main source code is on GitHub, so I want refer to this).

Using GitHub pages (with docs folder in master branch - I can't use gh-pages branch, because I want to change application and show demo in one commit) and manually creating subfolder for every change and paste somewhere link to file in specific folder (I know path to directory because I made this manually). This has many drawbacks too. It sounds very complicated (I made only simple page with D3.js!), I have to manually create folders, pay attention to paths and don't know how to deal with other branches than master (merges etc.).

Update 2020-07-07

Re: HtmlPreview or RawGit, 1. problem

I've found another service for serving HTML directly from GitHub raw.githack.com:

https://raw.githack.com/

This one is different from others in that it has support for production URL.

Use this URL in production
No traffic limits or throttling. Files are served via CloudFlare's CDN.

So I can create link with CDN:

https://rawcdn.githack.com/mkczyk/test-experiment/d7a4c7953d2b9084ca520eeb4434dd6d6689880d/index.html

I assumed that I don't have to worry about using this link in my public demos.

It solves my 1st problem from the way with serving HTML by external service. But 2nd problem with SHA remains. I still don't know how to dynamically create link to current commit in README.md. I submitted feature request for placeholder for hash of current commit: https://github.com/github/markup/issues/1363

来源：https://stackoverflow.com/questions/62740362/how-to-show-demo-with-html-and-javascript-d3-js-on-github-for-every-commit

标签

github