viewdocs.io should serve template support files (js, css, json, appcache)

[marfarma]

Currently attempting to link to http://{{user}}.viewdocs.io/{{name}}/assets/app.js returns 404 - file not found. Github's anti-hot-linking provision prevents the use of http://raw.github.com/{{user}}/{{name}}/docs/assets/app.js As a workaround I've added my script code to my template using a script tag. The same issue exists for css and json files. While that's not too bad, what's really awful is that I've had to do the same with my customized bootstrap.css - add it to the head in a style tag.

And while json files don't suffer from Github's anti-hot-linking provision - they are subject to same-origin restrictions via ajax access - leading me to embed json in a markdown file, and then parse it out from the rendered template after it's fetched from the server. This is further made difficult by the attribute stripping from markdown included html - see my other issue.

Are image files served? I haven't tested that yet. If not, and they can't be hot-linked, they should also be supported.

If security is a concern, perhaps enforce that non-markdown files served must be included in a manifest file at the same location as the template (whether or not the template includes a manifest tag), or only server files local to the docs directory and it's children?

[fgrehm]

According to @progrium's comment on #9 (comment), I risk saying this is "out of scope" in order to keep things simple on this project :-) A workaround is to use GitHub pages to serve those assets.

As per serving image files, I haven't tried it yet but my "gut feeling" tells me that unfortunately it won't work as well. If you end up trying it out please let us know how it goes!

[progrium]

Try using this: https://rawgithub.com/

On Thu, Jan 2, 2014 at 2:05 PM, Fabio Rehm notifications@github.com wrote:

According to @progrium https://github.com/progrium's comment on #9
(comment)#9 (comment),
I risk saying this is "out of scope" in order to keep things simple on this
project :-) A workaround is to use GitHub pages to serve those assets.

As per serving image files, I haven't tried it yet but my "gut feeling"
tells me that unfortunately it won't work as well. If you end up trying it
out please let us know how it goes!

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/21#issuecomment-31480146
.

Jeff Lindsay
http://progrium.com

[fgrehm]

Please don't do that!

[progrium]

Ah right. I forgot I only use it for local dev stuff. Scratch that
recommendation.

On Thu, Jan 2, 2014 at 2:22 PM, Fabio Rehm notifications@github.com wrote:

Please don't do thathttps://rawgithub.com/#what-will-happen-if-im-an-asshole
!

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/21#issuecomment-31481427
.

Jeff Lindsay
http://progrium.com

[marfarma]

I can use github pages to serve static assets, a hassle, but once the template is stable, it won't need to be touched. Having to rely on that for content embedded image files is more problematic, but still workable, as I expect them to be few and far between.

The same origin issue for json files still exists -- I can live with my current work-around for that, I guess, but I'd prefer otherwise.

[progrium]

Because of the caching viewdocs does and assumptions around Heroku that
viewdocs runs on, I don't think it will ever serve static content files. It
would be a significant change and I do think it's out of scope.

However, if we can come up with an easy solution to use GH Pages... maybe
another tool for publishing static files in /docs into the GH Pages branch
on pushes...

On Thu, Jan 2, 2014 at 2:34 PM, MarFarMa notifications@github.com wrote:

I can use github pages to serve static assets, a hassle, but once the
template is stable, it won't need to be touched. Having to rely on that for
content embedded image files is more problematic, but still workable, as I
expect them to be few and far between.

The same origin issue for json files still existshttp://stackoverflow.com/questions/18923328/is-there-a-way-to-enable-cors-on-github-pages-- I can live with my current work-around for that, I guess, but I'd prefer
otherwise.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/21#issuecomment-31482272
.

Jeff Lindsay
http://progrium.com

[marfarma]

Some iteration of this perhaps: http://jakebresnehan.com/post-commit-hook-for-github-pages/

Or actually, more like this: https://gist.github.com/Rich-Harris/6207294 - force gh-pages branch to match master and push both branches to origin at once

-- now how to configure gh-pages to serve assets from the docs directory -- hopefully trivial, but ...

[marfarma]

And .... the answer is, if you can see this file, http://marfarma.github.io/angular-pouch-model/docs/assets/css/demo.css it's working.

OK - it's a simple one-time setup, with all work local to your repository. Don't follow
any other gh-pages tutorials, as we're not publishing a site, just serving our static
assets from our /docs directory.

Start with an current clean repository, on the master branch. It's easiest to work from
a new clone. Create a gh-pages branch that is identical to your master branch:

git clone git@github.com:your-user/your-repo.git
cd your-repo
git branch gh-pages master

add a file, .git/hooks/post-commit with the following contents

#!/bin/sh
git branch -f gh-pages master

make it executable

chmod u+x .git/hooks/post-commit

edit your .git/config file so that the [remote "origin"] section looks like this:

[remote "origin"]
    url = git@github.com:your-user/your-repo.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    push = refs/heads/master:refs/heads/master
    push = refs/heads/gh-pages:refs/heads/gh-pages

this way, when you git push origin you automatically push both master and gh-pages branches

Tell Github that you are not using Jekyll

touch .nojekyll

Check in your changes and push to origin, adding the gh-pages branch to Github:

git add -A .
git commit -m "now serving assets from github.io"    
git push origin

Wait ten minutes for Github to notice your new gh-pages branch and start serving your files.

Now, in your templates you can reference:

http://{{user}}.github.io/{{name}}/docs/assets/css/demo.css

assuming you created a file demo.css and put it at assets/css relative to your docs folder.

[progrium]

This is great. Would you be interested in porting this to a page in the viewdocs docs directory?

[marfarma]

It should ideally be part of a longer document covering how to write templates. I'll throw something together as a first pass, maybe tonight.

[marfarma]

Correction - http://{{user}}.github.io/{{name}}/docs/assets/css/demo.css doesn't work. Template rendering doesn't replace {{user}} and {{name}} in script and stylesheet tags. Hard coding the replacement works. Should I create a separate issue for that?

[progrium]

yes, thanks

On Thu, Jan 2, 2014 at 9:35 PM, MarFarMa notifications@github.com wrote:

Correction - http://{{user}}.github.io/{{name}}/docs/assets/css/demo.csshttp://github.io/%7B%7Bname%7D%7D/docs/assets/css/demo.cssdoesn't work. Template rendering doesn't replace
{{user}} and {{name}} in script and stylesheet tags. Hard coding the
replacement works. Should I create a separate issue for that?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/21#issuecomment-31503488
.

Jeff Lindsay
http://progrium.com

[marfarma]

The pull request was merged: http://progrium.viewdocs.io/viewdocs/custom-layouts There are a few minor issues, principal among them that the {{USER}} and {{NAME}} tags were rendered. Is there any way to prevent them from being rendered - back ticks, code tags?

There needs to be a link to it from the main index.md page, once the issues have been cleaned up.

[marfarma]

See pull request #27 for template tag escaping.

[fgrehm]

FTR: Apparently https://rawgithub.com/ turned into https://rawgit.com/ and they now say it can be used for production!