
Simpler GitHub Pages publishing - dwaxe
https://github.com/blog/2228-simpler-github-pages-publishing
======
heyrhett
I love github pages. Here is a web game I helped make, hosted entirely on
github pages (made for the terrible ideas hackathon)

[http://scrollscore.com/](http://scrollscore.com/) "the more you scroll, the
more you win!"

[https://github.com/amberrayh/scrollscore/tree/gh-
pages](https://github.com/amberrayh/scrollscore/tree/gh-pages)

Thanks, Github, for making pages even better!

~~~
r3bl
You're requesting people to put their credit card info without having HTTPS
enforced by default? Doesn't sound suspicious at all.

What year is this? How is this still a thing?

~~~
heyrhett
Like i said, it was made for a terrible ideas hackathon.

Also, if you look at the source, you'll see that the form doesn't actually
post anywhere. It's a joke demo.

~~~
grennis
That's explains why my $1000 donation didn't go through

------
mintplant
Why make this such a limited set of options? Why not let me enter a path, for
example, instead of hardcoding "/docs"? What if I want to serve my docs from a
stable release branch or tag instead of "master"?

~~~
benbalter
We may make things more flexible down the line, but for now, it was motivated
by two primary reasons:

1\. The overwhelming majority of users use one of those three design patterns.
For example, I can tell you that more than 98% of GitHub Pages sites use
either `master` or `gh-pages` as their primary branch (with only about one
tenth of one percent of sites using the `stable` branch).

2\. Our experience tells us that every option we add to GitHub Pages increases
the learning curve for newer developers. With only those three options, if
you're just learning HTML, you don't need to understand Git's branching model
before you can create your first website.

We chose these options to start because we thought they struck a good balance
between supporting collaborative documentation workflows for open source
projects and encouraging "hello world" experimentation among new developers,
but as with most features at GitHub, this is just the start.

~~~
bsimpson
That's what defaults are for.

You have two choices to make: which branch and which path within that branch.
The defaults are "master" and "docs," but allowing maintainers to make
different choices there doesn't need to impact the onboarding experience for
new developers. The newbies use the defaults - people who need customization
can customize. Software development is a broad field and projects work within
various constraints and architectures. Asserting a convention here feels a bit
misguided.

You already allow the default branch to be customized. It's a bit weird that I
can specify a default branch (like "develop") and delete the master branch,
but then won't be able to publish docs without recreating master or
maintaining a gh-pages branch.

~~~
madgar
> Asserting a convention here feels a bit misguided.

Expecting GitHub to spend real money to cater to a tiny minority of users of
their web service is misguided. The business models behind public internet
services are simply not structured to cater to anything but the
lowest/simplest common denominator users.

~~~
bsimpson
I expect a reasonable amount of flexibility in developer tools, especially
since the difference between the current solution and the customizable one is
most likely two inputs in a web form.

It's great to see new features shipping on GitHub.com (especially since it
felt stagnant for so long). I have no idea what their codebase looks like, but
prepopulating a text field with the contents of a template.md file and
allowing the name of the publishing branch to be specified feel like they
should have been fairly minor changes. Especially now that they clearly have
the architecture to choose repo-specific publishing locations, allowing those
to be user-specified should be a very low-effort way to make the tools useful
for more projects.

------
aeharding
I recently switched to gitlab because they have a much more straightforward
pages publishing system.

It works by setting up a (free) pipeline which can run arbitrary code (docker-
ized) that you set up in a .gitlab-ci.yml file that outputs build artifacts
(static assets). These assets are then copied to gitlab's pages system.

Keeps your git repo clear of compiled stuff.

Works the same for public/private repos, too. Also has option for a custom
domain SSL cert and 404 pages.

~~~
ktta
You can use SSL with GitHub pages if you're using CloudFlare.

[https://blog.cloudflare.com/secure-and-fast-github-pages-
wit...](https://blog.cloudflare.com/secure-and-fast-github-pages-with-
cloudflare/)

And I think it works _only_ if you're using CloudFlare. I've always heard that
you can't use custom domains _and_ SSL but this works perfectly for me. But
can anyone say why? Since my website is now hosted by github, I'm not so
paranoid about my website going down or DoS attacks, and would like to not
depend on CF anymore.

~~~
daenney
It doesn't only work with Cloudflare but if you want to use a custom domain +
SSL you need to use a provider that can proxy the request for you. GitHub and
their Fastly setup won't serve custom certificates for you and the *.github.io
certificate wouldn't be valid for your custom domain.

~~~
ktta
The last sentence didn't really make sense to me. I assume Fastly is some kind
of backend tool? So why is it only working with CF? when I visit my custom
domain, I get a cert from sni75146.cloudflaressl.com but no cert related to
github to be seen anywhere. I'm assuming the cert I'm seeing is valid because
I'm viewing the page on CF's CDN, or am I wrong?

Well, I think I'm better off asking objective questions, so: 1\. Can I change
by DNS provider to something else and have SSL work? 2\. Can I keep using CF
and use my own cert, say from LetsEncrypt? 3\. Do GitHub and CF have something
in common/mutual agreement so this works?

~~~
daenney
Fastly is not "some backend tool". Two seconds of Google'ing would reveal to
you that they're a Content Distribution Network, aka CDN. They're the ones
actually serving the content hosted on *.github.io:

    
    
        host user.github.io
        user.github.io is an alias for github.map.fastly.net.
        github.map.fastly.net is an alias for prod.github.map.fastlylb.net.
        prod.github.map.fastlylb.net has address 151.101.12.133
    

Cloudflare doesn't act as a CDN in this case. What Cloudflare does is proxy
the request for you, and by virtue of them terminating the request they can
serve an SSL certificate for your domain (either handed out by them or custom
if you pay them).

~~~
ktta
Please see your sibling comment

------
ecesena
I would love to see a short guide on how to organize your open source website
on github (say a react website, since it's pretty popular), i.e. a recommended
workflow to store sources, implement new features, build artifacts/assets and
publish them on gh pages.

I did it in multiple ways, lately I had master with the code, and was pulling
gh-pages into the build/ directory, but I always wondered how other workflows
look like. And this changes/hopefully simplifies a ton.

~~~
bsimpson
It'd also be nice if there was a way to specify an HTML page that is served
for every path on the domain. That way, you could use an SPA architecture (a
container HTML file and a JS bundle that manages the URL) without breaking
deep links or needing to generate redundant pages to match every path in your
SPA.

~~~
ecesena
As a hack, I think you can set a custom 404.

~~~
bsimpson
Good tip - thanks!

[https://help.github.com/articles/creating-a-
custom-404-page-...](https://help.github.com/articles/creating-a-
custom-404-page-for-your-github-pages-site/)

------
munificent
Oh, God. This is truly the best thing out of all the things. Managing a gh-
pages branch was always a pain.

------
fuzionmonkey
For generated HTML docs or websites, this is still not ideal because you have
to commit generated code into your master branch.

You can even use Travis to automatically generate and deploy your
docs/website, which I find much cleaner and convenient than manually
publishing or committing generated code.

[https://github.com/L33T-KR3W/push-dir](https://github.com/L33T-KR3W/push-dir)
makes it easy to publish a directory to gh-pages (even .gitignored directories
i.e. build/).

~~~
transfire
The generated code is going to be "committed" somewhere, so I am not sure this
is much of a down side. I suppose one might worry about storing too much
history. Is there a way to pair down history for everything in docs/ ?

~~~
aorth
Slightly related, I push my site's generated code from the `public` directory
of my repo directly to the `gh-pages` branch using git's subtree push:

    
    
      $ git subtree push --prefix=public origin gh-pages

------
dstroot
Fabulous. As it should have been from day one - this is great.

------
1wheel
Is there anyway to make readme.md publish to github pages? I'd like to put
talk slide in readme.md, then load client side.

Like this, but without the duplicated file:
[https://github.com/1wheel/talks/tree/master/graphical-
web](https://github.com/1wheel/talks/tree/master/graphical-web)

~~~
r3bl
I agree with you.

I think that at the very minimum automatic page generation should convert the
README file to HTML by default.

I would love to see an option to sync the README file with the site without
playing with Git hooks.

------
kannonboy
Aerobatic ([https://www.aerobatic.com/](https://www.aerobatic.com/)) takes a
similar, though slightly more flexible, approach with their static site
deployments for Bitbucket.

You pick a branch then (optionally) specify a sub-directory of your repository
to deploy.

(full disclosure: I'm at Atlassian)

------
voiper1
TL;DR: For serving pages, you can now use `/docs` in your master branch
instead of needing a `gh-pages` branch.

------
wildpeaks
Beyond not managing an extra branch, the best benefit imho is when you work on
a feature branch, you can also update the docs while working on the feature,
so the docs are part of the pull requests and only merged once the new code is
merged, so it stays in sync without an extra step.

------
jerluc
This is great news for me, maybe now I can finally merge my documentation
repository with my code repository and have it make sense again :)

On another note, I wonder how I could change my Nanoc deploy to support this
new kind of Github Pages setup (currently, it follows this process:
[http://nanoc.ws/doc/deploying/#with-github-pages-or-
bitbucke...](http://nanoc.ws/doc/deploying/#with-github-pages-or-bitbucket)).

------
kevin_thibedeau
They should also add a way to turn off Jekyll processing so you don't have to
remember to add a .nojekyll file.

~~~
hk__2
Well, adding a .nojekyll file _is_ a way to turn off Jekyll processing ;)

------
tomphoolery
This is exactly how I wanted GitHub Pages to work since it was introduced.
Thank you!

------
simplehuman
So, does this mean that the folder is always "live" ?

------
transfire
YEAH!!!!!!!!!!!!!!!!! Good job guys, you did it! Ok, one small peeve: I think
a directory name like `site` would have been better than `docs` because it has
a more generally applicable meaning. But hey, I can live with `docs`, even if
it means having a `docs/docs` path. I'm just glad this is finally a feature!
Kudos.

------
artf
Thanks GitHub and thanks for your Pages. I'm maintaining a web template editor
[http://grapesjs.com/demo.html](http://grapesjs.com/demo.html) Where you can
design, store and even export to zip responsive templates without much effort
and totally free. Really, thank you

------
lettergram
I'm ecstatic for this! I was getting real sick of keeping the separate
branches up to date, when I wanted to make a minor change.

------
geraldbauer
Fantastic news. Makes static sites publishing way easier. Looking forward to
the upcoming gem-packaged themes (in Jekyll) on GitHub pages too.

PS: Anyone interested in static (web)site builder news (e.g. GitHub Pages,
Jekyll, Middleman, Gatsby, Metalsmith, and friends)? Follow along @statictimes
on twitter ->
[https://twitter.com/statictimes](https://twitter.com/statictimes) PPS: Anyone
interested in Jekyll - I've put together an Awesome Jekyll page ->
[https://github.com/planetjekyll/awesome-
jekyll](https://github.com/planetjekyll/awesome-jekyll) (incl. a history on
GitHub Pages updates/news).

