Creating an organization site

# Creating a Github Pages Organization Website
This was not exactly straightforward. No GitHub documentation directly walks you through this process - so I am documenting it here.

# Scenario
Let's say your organization is called 'AcmeWidgets' and you want to have your website at the root URL of your Github Pages website: https://acmewidges.github.io/

You also want to do the following, which doesn't seem SO weird, right?
- You are using something like Yeoman or Jekyll to manage your organization site
- You want your DISTRIBUTION files to exist on a branch on your repository
- You want your SOURCE files to exist in another branch.

How do you do this? Github is not entirely helpful. [This page](https://help.github.com/articles/user-organization-and-project-pages/) says your distribution files must be in the MASTER branch of your USER or ORGANIZATION repository. The example it gives is `<organization>.github.io` where `<organization>` is your repository name. 

Ok, so you happy go create https://github.com/acmewidgets/acmewidgets, publish some files to the `master` branch, and then go to your Settings page.... where it confidently tells you your website is published to https://acemewidges.github.io/acmewidgets/. 

Wait what? That's not what you wanted. You want it to be at http://acmewidges.github.io. So how do you fix this?

What you must find [SOMEWHERE ELSE](https://pages.github.com/), in a blurry, hard to read image embedded in the page, is that your repository must not be named `acmewidgets` - it must be named `acmewidgets.github.io`. Yes the repository name itself must contain the entire URL.

So, go rename your repository. Check settings. You are told `Your site is published at https://acmewidgets.github.io/`. Success!

# Splitting your branches
Now, you want to manage the distributed code separate from the source code, for building. But you don't want to do this in a separate repo. Branches are always just forks of each other, right? 

Time to learn about a little known Git command called `git subtree`. What `git subtree` does is insert a branch as a subdirectory of your tree.

So let's say in your master branch, you have your files laid out like this:
.
├── _config.yml
├── dist
│   ├── about.html
│   ├── index.html
│   └── assets
│       ├── css
│       │   └── main.css
│       └── main.png
└── source
    ├── Gemfile
    ├── Gemfile.lock
    ├── about.md
    ├── index.md
    └── _posts
        ├── 2016-10-05-My-first-post.markdown
        └── 2016-10-05-My-second-post.markdown

You want that `dist` folder to be the one that gets deployed. You want to store `source` in its own branch, build dist, and deploy it.

Bear with me. Run the following commands:

``` bash
> git checkout -b gh-pages (you can name this whatever you want. For consistency...)
> git push --set-upstream origin gh-pages
```
At this point, go to your repo, go to Settings -> Branches and set gh-pages as the primary branch. Now, go to http://github.com/acmewidgets/acmewidgets.github.io/branches and DELETE the master branch. Yep - you heard me. You'll see why.

``` bash
> git branch -d master (deleting the local copy too)
> git subtree add --prefix dist/
> git subtree push --prefix dist/ origin master <<-- this is why we deleted the master branch! We are re-creating it with the dist folder.
```
The `git subtree push` command takes care of pushing the new master branch to your repo. If you now visit http://acmewidges.github.io in your browser, you will see your dist folder presented as a webpage!

To maintain your website, gh-pages is now your primary branch, so any `git clone` commands automatically pull down gh-pages. This is a good thing! It means you get started editing your website right away. Anytime you change your site in `source`, simply run `jekyll build` and then the `git subtree push` command again, as above.