The easiest way to start blogging with Middleman + HTML5 + foundation.
Table of Contents generated with DocToc
- Overview - Features - Requirements - Steps - Reasoning
- Usage - Clone - Download - Configure - Run - BitBalloon Setup - Upgrade Foundation
- Contributing - Getting Started - Steps
- Workflow - Markdown - Git Remote - Git Push and Pull
- License
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.
- Based on the middleman-foundation and middleman-zurb-foundation projects.
- Created with the init.sh and setup.sh scripts.
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!
- Middleman built from the HTML5 boilerplate. Written in Ruby.
- Blogging with support for articles, categories and tags.
- Nokogiri for HTML-aware article summaries.
- LiveReload to automatically refresh your page after changes.
- Pretty URLs without .html at the end.
- kramdown handles Markdown with built-in support for fenced code blocks, footnotes, tables and smart quotes. Written in Ruby.
- Rouge for syntax highlighting. Also written in Ruby and enabled by the middleman-syntax extension.
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.
- Ruby 1.9+ and RubyGems
- Node.js and npm:
yum install nodejs npm
- Middleman and foundation gems:
gem install middleman foundation
- bower:
npm install -g bower
These are the basic steps that are performed by the setup.sh script.
- middleman init MY_PROJECT --template=html5
- middleman init MY_PROJECT --template=blog
- foundation new MY_PROJECT
- 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
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
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
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 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 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
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:
- do an initial manual drag and drop deploy of your new site
- go to your site in the BitBalloon UI
- click "Link site to a GitHub repo" at the bottom right
(currently a beta feature so you may need to request access) - choose which branch you want to deploy (typically master)
- set the directory to
Other ...
enter/build
- 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!
If you'd like to upgrade to a newer version of Foundation down the road:
- Specify the version you want to update to in the bower.json file.
- Then run
bower update
Contributions are totally welcome.
A clear intro to using git.
A good step-by-step guide about how to contribute to a GitHub project like this one.
- fork http://github.com/keegoid/middleman-html5-foundation/fork
- 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
- HTTPS:
- optionally create your own feature branch
git checkout -b my-new-feature
- commit your changes
git commit -am 'made some cool changes'
- push your master or branch commits to GitHub
git push origin master
git push -u origin my-new-feature
- create a new Pull request
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
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 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.
Author : Keegan Mullaney
Company: KM Authorized LLC
Website: http://kmauthorized.com