As I mentioned before, it has been a long time to-do item for me to get a blog/website up and running. I finally pulled the trigger and this is a result. This is the down a dirty guide..
- Step 1: Select hosting
- Step 2: Getting Jekyll running
- Step 3: Select your Theme and run locally.
- Step 4: Finishing up
Step 1: Select hosting
Github Pages has some good documentation on setting up the repo - for me, I wanted this to be my github user site, so I created the repo
jakevis.github.io, and enabled pages on this site. I also associated it my
jv.ag domain, and set it to require https.
If you are using a custom domain name, you do need to setup a cname, alias or apex record. For me, this was an alias record - and you simply point it to your default github pages site (so for me
Step 2: Getting Jekyll running
My day to day machine is Windows 10 - so these instruction as for that. If your using Mac or Linux, changes are you have ruby allready installed, and can skip the first bit, or gem is avalible for your package manager.
For windows - go to https://rubyinstaller.org/downloads/ and download the the recommended version (with devkit).
Follow the bouncing ball for installation once downloaded.
gem should be avalible to you on your command line. Verify with:
Now install bundler and jekyll.
gem install bundler jekyll
This may take some time as it fetches what it needs from the interwebs.
Step 3: Select your Theme and run locally.
So with luck you allready have an idea of what theme you intent to use. Github Pages has a bunch that are supported by default (https://pages.github.com/themes/), you could build you own… or do what I did and find another one on the interwebs that you like.
The process is somewhat the same for all, but do check the documentation of the theme as to file layout and required files.
My selection was this theme: https://github.com/mmistakes/minimal-mistakes; and luckly they also provide a sample site using said theme: https://github.com/mmistakes/mm-github-pages-starter
To get up and running I downloaded this starter code, and committed it to my repo. You can use github desktop or whatever your preference is for handing git.
git init git add . git commit -m "Initial commit" git remote add origin https://github.com/jakevis/jakevis.github.io.git git push origin master
Next I customized my Gem file. As I wanted to build and test the site locally, and while on the road without pushing everything to the site live. My Gem file ended up like this:
source "https://rubygems.org" gem "github-pages", group: :jekyll_plugins gem 'jekyll-include-cache' gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw] gem 'wdm', '~> 0.1.0' if Gem.win_platform?
gem "github-pages", group: :jekyll_plugins: is used to tell jekyll to use github pages (for theming ect)
gem 'jekyll-include-cache': Needed by this theme
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw]: allows me to set my timezone and have it work correctly
gem 'wdm', '~> 0.1.0' if Gem.win_platform?: Removes a depandacy check - speeds the local build up a tad.
Next we should customize the
_config.yml file a tad. Follow the bouncing ball, most of it just needs personalization. I did add bing verification to mine, as well as google analytics; and a link to LinkedIn. Here is mine for reference, but refer to the master theme for all options: https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml
Note I have shortened the description felid to make it render correctly. If you change
>- you can the enter multiple lines of text.
title: Jakes Site of Random Musings email: firstname.lastname@example.org description: url: https://jv.ag twitter_username: jakevis_ github_username: jakevis minimal_mistakes_skin: dark search: true search_full_content: true logo: #"" repository: "jakevis/jakevis.github.io" # Build settings markdown: kramdown remote_theme: mmistakes/minimal-mistakes # Outputting permalink: /:categories/:title/ paginate: 5 # amount of posts to show paginate_path: /page:num/ timezone: America/Los_Angeles bing_site_verification: E777B921F80745027DAA711311DEFC0E include: - _pages # Exclude from processing. # The following items will not be processed, by default. Create a custom list # to override the default setting. # exclude: # - Gemfile # - Gemfile.lock # - node_modules # - vendor/bundle/ # - vendor/cache/ # - vendor/gems/ # - vendor/ruby/ # Plugins (previously gems:) plugins: - jekyll-paginate - jekyll-sitemap - jekyll-gist - jekyll-feed - jemoji - jekyll-include-cache author: name : "JakeVis" avatar : "/assets/images/bio-photo.jpg" bio : "Jack of all, master of **none**" location: "Seattle, WA, USA" links: - label: "Website" icon: "fas fa-fw fa-link" url: "https://jv.ag" - label: "LinkedIn" icon: "fab fa-fw fa-linkedin" url: "https://www.linkedin.com/in/jakevisser/" - label: "Twitter" icon: "fab fa-fw fa-twitter-square" url: "https://twitter.com/jakevis_" - label: "GitHub" icon: "fab fa-fw fa-github" url: "https://github.com/jakevis" #- label: "Instagram" # icon: "fab fa-fw fa-instagram" # url: "https://instagram.com/" analytics: provider : google # false (default), "google", "google-universal", "custom" google: tracking_id : UA-145874977-1 anonymize_ip : false # true, false (default) footer: links: - label: "LinkedIn" icon: "fab fa-fw fa-linkedin" url: "https://www.linkedin.com/in/jakevisser/" - label: "Twitter" icon: "fab fa-fw fa-twitter-square" url: "https://twitter.com/jakevis_" - label: "GitHub" icon: "fab fa-fw fa-github" url: "https://github.com/jakevis" #- label: "Instagram" # icon: "fab fa-fw fa-instagram" # url: "https://instagram.com/" defaults: # _posts - scope: path: "" type: posts values: layout: single author_profile: true read_time: false comments: false share: false related: true # _pages - scope: path: "_pages" type: pages values: layout: single author_profile: true category_archive: type: liquid path: /categories/ tag_archive: type: liquid path: /tags/
Next is to get this running locally. For this, change into your repo’s directory and execute:
This should pull down all the required packages and set everything up.
Once done it should conclude with:
If so, your now right to run it.. to get going I use:
bundle exec jekyll serve --drafts --incremental
Once running you should be able to go to http://127.0.0.1:4000/ and see your page.
--incremental: This is experimental still, but speeds up rebuild times
--drafts: This enabled rendering a
_drafts folder. When published to github, this folder is ignored; so its handy to put unfinished work in here prior to go-live.
Step 4: Finishing up
So if your site runs localy; it should run on github too. Just commit and push your changes and you should be set. If you screw something up and it fails to build… github will email you:
In my case I tried to configure the
_drafts folder to be a submodule (in a private repo).. for the record this isnt supported.