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"?
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.
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.
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.
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.
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:
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.
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.
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?
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).
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
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.
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.
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.
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.
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/ ?
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.
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
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).
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!