Simpler GitHub Pages publishing | Hacker News Reader

Simpler GitHub Pages publishing

github.com

275 pointsdwaxe63 comments

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/ "the more you scroll, the more you win!"

https://github.com/amberrayh/scrollscore/tree/gh-pages

Thanks, Github, for making pages even better!

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?

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.

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

This needs a few layers of obnoxious javascript to put it over the top. Funny idea.

This is great. I mean, it's lousy and I am over it, but it is somehow perfect, in a Kantian way, as a thing unto itself.

1. concerns about HTTPS are legit.

2. I'd really rather see the $$$ you're making as my score, than this arbitrary number on the side.

3. let's get more/different ads up there!

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"?

The benefit of limiting options is to keep it standardised for most OSS projects, which I like.

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.

Personally speaking, I think this is a great idea. Great job!

Great! Please don't give in to the demand for added flexibility without strong justification. Just as it did with README.md, GitHub has an opportunity to drive successful conventions and global simplifications that virtually no other organization in open source can.

I'm not sure if you're being sarcastic, but README file was a convention for decades literally.

Not sarcastic at all. First, I said README.md. Markdown in readmes was popularized - if not invented by - GitHub. Furthermore, the top billing of README.md files in the GitHub UI took over from more traditional meta-level documentation that used to be in separate places, such as an "About" field/page on SourceForge or a separate web page. I much prefer this documentation in repository. Even if projects had READMEs, they might not include certain information there previously.

All these things are just GitHub's implementation and UX details. The README file is the traditional meta-level documentation (if I correctly understand what you mean by that: top level document that gives a more or less comprehensive overview of the project). READMEs always included this information, sometimes offloading details of particular topics into INSTALL, AUTHORS, LICENCE, etc. files. GitHub just figured they might as well use the thing as intended and actually render it on a web page. As for markup, people were already using email like markup in those files, so this is again just following established practice to its logical conclusion and modern implementations. GH's sole innovation in convention here is tacking on the very annoying file type extension in order to not have to figure out the format automatically.

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.

> 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.

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.

> Expecting GitHub to spend real money to cater to a tiny minority of users

You must be new here...

Thank you for making a sane default based on actual usage data. BTW, for people who need something a bit different, I have been using this for one of my sites that is hosted on GitHub:

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

The `public` directory is where the HTML/CSS/JS generated by my static site generator and I push that subtree to the gh-pages branch.

Favorited for later. Thanks, that's useful!

Why /docs instead of something more encompassing like /site or /pages?

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.

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

https://blog.cloudflare.com/secure-and-fast-github-pages-wit...

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.

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.

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?

No no and no. Custom certs are for Cloudflares paying customers. You can use Cloudflares with any host. It's basically a reverse dns proxy.

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).

Please see your sibling comment

>>So why is it only working with CF?

Because CloudFlare is basically a MITM Attack.... that is authorized by the website owner.

http://blog.ricardomacas.com/index.php?controller=post&actio...

https://stirling.co/blog/cloudflare-mitm/

Thanks for the replies everyone. Turns out my understanding of what CF exactly did was a bit iffy.

@daenney - should've googled, and is that some online dig tool? or just you typing it that way?

@syshum - Huh, I remember read up on it about how piratebay was inaccessible in India because of CF

@angry-hacker - CF does offer free certs. I was actually wondering why only CF's certs worked with github pages, but not anyone else.

But I now understand that any one who thinks they're visiting the page on github pages are actually visiting CF's server because CF cached my stuff on github. And because it is on CF's server, they are able to show a HTTPS cert. I hope I got it right this time

I'm not going to switch to Gitlab, because someone took my Github/Gmail/Twitter/HN handle. :(

Why not just sign in with Gmail? The only reason that I see to not do it would be that someone could think that the other person is you - but that can happen nonetheless.

Did you know GitLab has pages too? https://pages.gitlab.io/

It supports many generators https://gitlab.com/groups/pages and custom domains work even on free accounts.

That's what I'm talking about...?

Oops, misread your comment. Sorry, and thanks for talking about GitLab.

No problem, thanks for making such a great product. Keep it up.

Thanks! We'll announce an awesome new feature this Monday.

Doesn't sound very straightforward to me.

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.

There's a great Ember addon for this: https://github.com/poetic/ember-cli-github-pages

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.

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

Good tip - thanks!

https://help.github.com/articles/creating-a-custom-404-page-...

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

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 makes it easy to publish a directory to gh-pages (even .gitignored directories i.e. build/).

Agreed. I use https://readthedocs.org to take care of building and hosting documentation, and it's really handy.

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/ ?

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

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

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

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.

Aerobatic (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)

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

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.

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...).

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

Well, adding a .nojekyll file is a way to turn off Jekyll processing ;)

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

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

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.

Thanks GitHub and thanks for your Pages. I'm maintaining a web template editor 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

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.

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 PPS: Anyone interested in Jekyll - I've put together an Awesome Jekyll page -> https://github.com/planetjekyll/awesome-jekyll (incl. a history on GitHub Pages updates/news).

Reply on news.ycombinator.com