/middleman-html5-foundation

A template for a Middleman site with the HTML5 Boilerplate, the middleman-blog extension and the Sass/Compass version of Zurb's Foundation 5. (INCOMPLETE)

Primary LanguageShellOtherNOASSERTION

middleman-html5-foundation

The easiest way to start blogging with Middleman + HTML5 + foundation.

Table of Contents generated with DocToc

Overview

A base Middleman site with the HTML5 Boilerplate, the middleman-blog extension and the Sass/Compass version of Zurb's Foundation 5.

For static websites, I use BitBalloon because whenever I push to GitHub, BitBalloon will automatically run Middleman and deploy the /build folder to my site. It's a nice convenience for Middleman sites. Instructions for the [BitBalloon setup][#bitballoon-setup] ar below.

I prefer doing things with shell scripts rather than starting from a template without knowing how it was created. If you're interested to see how this repository was created, you can see each step in the setup scripts. You can run those scripts to get your own site in under 5 minutes! I hope you like it!

Features

Since Middleman is written in Ruby, it makes sense to try to stick with Ruby for Middleman extensions whenever possible. That's why I like kramdown with Rouge for Markdown and syntax highlighting.

To see all the available options and features, run Middleman with the preview web server:

cd my_project
bundle exec middleman

Then go to http://localhost:4567/__middleman/config/ in your browser.

Requirements
Steps

These are the basic steps that are performed by the setup.sh script.

  1. middleman init MY_PROJECT --template=html5
  2. middleman init MY_PROJECT --template=blog
  3. foundation new MY_PROJECT
  4. some copying, deleting and editing to merge the three templates

To start working on your project and see live changes at http://localhost:4567, just run:

cd MY_PROJECT
bundle exec middleman
Reasoning

I made this project to gain a better understanding of Middleman, HTML5, HAML and Sass using the Sass/Compass version of Foundation 5.

Using shell scripts with Middleman and Foundation fits well with my workflow since I use CentOS for my programming work. It's a pretty stable Linux distribution. I like it a lot and use it on my laptop and servers at DigitalOcean.

If this script helps you to better understand CentOS, shell scripting, Linux in general or if they help you to setup your own Middleman site, please do let me know: @keegoid

Usage

Clone

This method directly downloads the project to your local repository where you can start making changes.

Clone this project using HTTPS or SSH (recommended):

  • HTTPS: git clone https://github.com/keegoid/middleman-html5-foundation.git
  • SSH: git clone git@github.com:keegoid/middleman-html5-foundation.git
Download

Optionally, you can get it by downloading the config.sh and init.sh scripts. This option will build everything step-by-step so you can see exactly what happens.

# download the scripts
curl -kfsSLO https://raw.githubusercontent.com/keegoid/middleman-html5-foundation/master/config.sh
curl -kfsSLO https://raw.githubusercontent.com/keegoid/middleman-html5-foundation/master/init.sh
Configure

Configure config.sh before running init.sh.

####################################################
# EDIT THESE VARIABLES WITH YOUR INFO
USER_NAME='kmullaney' #Linux user you will/already use
REAL_NAME='Keegan Mullaney'
EMAIL_ADDRESS='keegan@kmauthorized.com'
SSH_KEY_COMMENT='CentOS workstation'
MIDDLEMAN_DOMAIN='keeganmullaney.com'
GITHUB_USER='keegoid' #your GitHub username
LIB_DIR='includes' #where you put extra stuff
####################################################
Run

Run init.sh and it will download setup.sh plus a few library files. Then run setup.sh.

chmod +x init.sh
./init.sh #run as root user
./setup.sh #run as non-root user
BitBalloon Setup

To set up the automatic BitBalloon deploys, log in as a non-root user.

# cd to your Middleman project directory and install run:
bundle install

# optionally, run the local middleman server at http://localhost:4567/
# to confirm that your new site is functional:
bundle exec middleman

# commit your changes with git:
git commit -am 'first commit'

# push commits to your remote repository (GitHub):
git push origin master

go to the BitBalloon site and:

  1. do an initial manual drag and drop deploy of your new site
  2. go to your site in the BitBalloon UI
  3. click "Link site to a GitHub repo" at the bottom right
    (currently a beta feature so you may need to request access)
  4. choose which branch you want to deploy (typically master)
  5. set the directory to Other ... enter /build
  6. for the build command, set: bundle exec middleman build

Now whenever you push changes to Github, BitBalloon will run middleman and deploy the /build folder to your site automatically. Easy!

Upgrade Foundation

If you'd like to upgrade to a newer version of Foundation down the road:

  1. Specify the version you want to update to in the bower.json file.
  2. Then run bower update

Contributing

Contributions are totally welcome.

Getting Started

A clear intro to using git.
A good step-by-step guide about how to contribute to a GitHub project like this one.

Steps
  1. fork http://github.com/keegoid/middleman-html5-foundation/fork
  2. clone your own fork using HTTPS or SSH (recommended)
    • HTTPS: git clone https://github.com/yourusername/middleman-html5-foundation.git
    • SSH: git clone git@github.com:yourusername/middleman-html5-foundation.git
  3. optionally create your own feature branch git checkout -b my-new-feature
  4. commit your changes git commit -am 'made some cool changes'
  5. push your master or branch commits to GitHub
    • git push origin master
    • git push -u origin my-new-feature
  6. create a new Pull request

Workflow

Markdown

After much tribulation with Markdown editors and various workflows, I've found what I think is a great way to create/maintain my Markdown docs.

For blog posts or any long-form writing Draft is wonderful, especially the F11 mode. It mostly works with GitHub Flavored Markdown except for strikethrough and alignment of table columns. I then Export my document to the appropriate git repository in Dropbox (which then syncs with my various devices). Finally, I commit the new document with git and push it to GitHub (which then gets automatically built and deployed on BitBalloon).

For other Markdown docs like README.md or LICENSE.md I find gEdit to be easy and efficient. I can make some quick edits, commit changes in git and push them to GitHub with just a few commands. It's also easy to repeat commits and pushes with the keyboard up arrow from the Linux console.
to commit again: up up enter, to push again: up up enter

Git Remote

If you didn't start by cloning this repository on GitHub, for example if you used git init on your workstation, you'll need to add your remote origin URL:

# HTTPS:
git remote add origin https://github.com/yourusername/middleman-html5-foundation.git

# SSH:
git remote add origin git@github.com:yourusername/middleman-html5-foundation.git

You can also set the upstream repository to fetch changes from this project:

# HTTPS:
git remote add upstream https://github.com/keegoid/middleman-html5-foundation.git

# SSH:
git remote add upstream git@github.com:keegoid/middleman-html5-foundation.git

Then git fetch upstream master and git merge upstream/master
or accomplish both with git pull upstream master

Git Push and Pull
# git config
# author
git config --global user.name 'Keegan Mullaney'
git config --global user.email 'keegan@kmauthorized.com'
# select a text editor, I prefer vi, you can also use vim or something else
git config --global core.editor vi
# add some SVN-like aliases
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.up rebase
git config --global alias.ci commit
# set the default push and pull methods for git to "matching"
git config --global push.default matching
git config --global pull.default matching

# commit changes with git
git commit -am 'update README'

########## new branch method 1 ##########

# create a new branch and check it out
git checkout -b 'branch-name'

# push changes to remote repo and set remote upstream in config
git push -u origin branch-name

# checkout the master branch again
git checkout master

########## new branch method 2 ##########

# create new branch without checking it out
git branch 'branch-name'

# push new branch to origin
git push origin 'branch-name'

# link the origin/<branch> with your local <branch>
git branch -u origin/branch-name branch-name

Now you can simply use git push or git pull from your current branch, including master. It's nice to be able to reduce the length of these commands so you don't have to think about what you're pushing or pulling each time. Just make sure you've got the right branch checked out!

long versions

push or pull changes to/from origin (GitHub):
git push origin master or git push origin branch-name
git pull origin master or git pull origin branch-name

Note, use git config --list to view all configured options.

I hope you find this workflow as efficient and effective as I do.

License

Author : Keegan Mullaney
Company: KM Authorized LLC
Website: http://kmauthorized.com

MIT: http://kma.mit-license.org