Simpler GitHub Pages publishing

https://github.com/blog/2228-simpler-github-pages-publishing

by dwaxe • 10 years ago

275 63 10 years ago

dstroot• 10 years ago

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

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

saghul• 10 years ago

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

transfire2• 10 years ago

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

aorth2• 10 years ago

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

geraldbauer• 10 years ago

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

aeharding3• 10 years ago

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.

ktta4• 10 years ago

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.

daenney2• 10 years ago

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.

echelon• 10 years ago

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

harperlee• 10 years ago

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.

sytse3• 10 years ago

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.

aeharding3• 10 years ago

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

nicky0• 10 years ago

Doesn't sound very straightforward to me.

simplehuman• 10 years ago

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

mintplant2• 10 years ago

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

andruby2• 10 years ago

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

benbalter• 10 years ago

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.

sn0v• 10 years ago

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

brandonbloom2• 10 years ago

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.

bsimpson4• 10 years ago

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.

aorth2• 10 years ago

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.

cpeterso• 10 years ago

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

ecesena2• 10 years ago

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.

andruby2• 10 years ago

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

bsimpson4• 10 years ago

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.

ecesena2• 10 years ago

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

kevin_thibedeau• 10 years ago

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• 10 years ago

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

jerluc• 10 years ago

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

munificent• 10 years ago

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

heyrhett2• 10 years ago

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!

r3bl2• 10 years ago

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?

heyrhett2• 10 years ago

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.

chestervonwinch• 10 years ago

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

rexpop• 10 years ago

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!

1wheel• 10 years ago

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

r3bl2• 10 years ago

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.

lettergram• 10 years ago

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.

tomphoolery• 10 years ago

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

artf• 10 years ago

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

transfire2• 10 years ago

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.

kannonboy• 10 years ago

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)

voiper1• 10 years ago

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

wildpeaks• 10 years ago

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.

Simpler GitHub Pages publishing

Related Stories