If I’d known there’d be so much typing, I would have worn gloves
Estimated reading time: six minutes
- Tagged with
- GitHub Pages
- Middleman
- OSX
- rbenv
- Ruby
Generating a website on O.S.X. 11 with Middleman 4.0.0 and hosting it with GitHub. This is an idiots guide, the idiot being me. I had a frustrating time setting up this site and wanted to ease future installations with an aide-mémoire. Hopefully someone else might find this useful.
You should never ever enter into the Terminal commands you find in comments, on forums, or on personal websites like this one unless you understand what they are doing and not just what someone like me is claiming that they do. The terminal can do bad things to your computer. That said, these are the steps I took to install Middleman and they are a whole bunch of terminal commands.
Directories and folders are the same thing. However, to both follow convention and increase confusion, I am using directory when referring to the command line and the Terminal application and folder when accessing the same thing using Finder.
Ruby uses software packages called gems which each contain an application or library.
Installing the software to support Ruby
Install Xcode command line tools
Why do you want to install the Xcode command line tools? Because you want Ruby.
Open the Terminal (by default it will open into your home folder which is fine) and enter:
code-select –install
From Middleman’s installation instructions.
Install Homebrew
Why do you want to install Homebrew? So that you can install rbenv.
To install Homebrew enter:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
From Homebrew’s homepage.
To check if the installation is okay, you can enter:
brew doctor
If it does show any issues, you’ll get no help from me.
Install rbenv
Why do you want to install rbenv? So that you can have multiple versions of Ruby installed.
Even if you don’t want to work on different projects with different versions of Ruby using the same computer, Apple’s version of Ruby is updated at Apple’s leisure. At some point, something you install will require a newer version of Ruby.
rbenv basically redirects requests for ruby files to the version that matches the first .ruby-version
file it finds by first searching the directory of the script you are executing and each of its ancestor directories until reaching the root of your filesystem. This means you can change the ruby version for your whole home directory, a collection of directories, and an individual directory.
In the Terminal enter:
brew install rbenv ruby-build
To complete the installation you also need to enter:
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
Followed by:
rbenv init
Install an up-to-date version of Ruby
At the time I first published this, the most up to date version of Ruby was 2.3.0.
Installing Ruby
rbenv install 2.3.0
Using that Ruby version for your website
Create a new folder: my_test_website
. Navigate Terminal to this directory as it is where the rest of the commands will be entered.
Using a text editor, create a new file with the contents:
2.3.0
Save the file as my_test_website\.ruby-version
. This will determine that when working in my_test_website
, you will be using Ruby version 2.3.0.
Installing Middleman
Gems
Install the Middleman gem by entering:
gem install middleman
Then install the Middleman blog gem by entering:
gem install middleman-blog
Create a new site by entering:
middleman init --template=blog
This will populate my_test_website
with all the Middleman files for your website.
Add to GitHub
Add the folder to GitHub Desktop as a new repository. Make an initial commit of the existing files and then rename the branch from “master” to “source”. You need to make a commit before you can rename the branch and for a user or organization site
the published site needs to be published into the “master” branch. Therefore, the code to generate it needs to be in another branch.
Licence and read me files
Assuming that you have a licence.txt
and a README.markdown
file, to copy these unchanged from the my_test_website
root directory into your build directory, add the following to config.rb
after # Build-specific configuration
section:
# Copy files to build folder after build
after_build do
print 'After_build fixes … '
system("cp \licence.txt #{config[:build_dir] + '/licence.txt'}")
system("cp \README.markdown #{config[:build_dir] + '/README.markdown'}")
puts 'done.'
end
Deploying on GitHub
Install the Middleman deploy gem. At time of writing the current release of middleman-deploy is incompatible with Middleman 4.0.0 so you need to use middleman-deploy version 2.0.0.pre.alpha.
Add gem 'middleman-deploy', '~> 2.0.0.pre.alpha'
to my_test_website\GEMFILE
and whilst you’re there, remove the windows specific gems by deleting the following:
# For faster file watcher updates on Windows:
gem 'idm', '~> 0.1.0', platforms: [:mswin, :mingw]
# Windows does not come with time zone data
gem 'tzinfo-data', platforms: [:mswin, :minnow, :jruby]
Then enter:
bundle install
Open my_test_website\config.rb
and, after the # Copy files to build folder after build
, or if not present than the # Build-specific configuration
section, add the following:
# Deploy to GitHub
activate :deploy do |deploy|
deploy.build_before = true
deploy.deploy_method = :git
deploy.branch = 'master'
deploy.commit_message = 'Published from build of source branch'
end
Problems with Jekyll
GitHub has integrated support for another built in static website generator, Jekyll, this could cause problems with your site.
Create the following empty file:
my_test_website\source\.nojekyll
This should only be necessary if your site uses directories that begin with an underscore, as Jekyll sees these as special directories and does not copy them to the final destination.
From GitHub pages help files: Turning off Jekyll.
Avoid git prompt for username and password
Publish your repository using GitHub Desktop. This will generate the rest of the configuration details for your repository.
If your GiHub password is short and easy to remember, change it. To avoid being prompted to type in your 30 characters long randomly generated password open the .git/config
in your text editor.
Look for a line where the beginning matches url = https://github.com/
and change that to url = ssh://git@github.com/
(thanks to ‘Shiva’).
In conclusion
You should now have a website published on GitHub. It is, of course, full of dummy text and only populated by an outdated example post. I wasn’t trying to cover setting up a website or a GitHub repository, just the awkward confluence of the two.