The Habitat.sh developer blog built to make it possible for any community member to be able to contribute. Got a crazy experiment you tried and want to publish your writeup? Great, we’d love to publish you! Feel like the thing you just built in dev came with a lot of knowledge you’re interested in sharing. Fantastic, let’s get it out there for folks to read.
The blog exists in the habitat-sh/habitat repo under the www directory.
$ cd habitat/www/source/blog && ls -l
-rw-rw-r-- 1 eeyun eeyun 2.4K Jul 28 19:17 2017-04-11-Hello-World.html.md
-rw-rw-r-- 1 eeyun eeyun 7.2K Jul 28 19:17 2017-04-12-Multi-Service-Supervision.html.md
-rw-rw-r-- 1 eeyun eeyun 5.5K Jul 28 19:17 2017-05-16-brupal-twice.html.md
-rw-rw-r-- 1 eeyun eeyun 8.2K Aug 16 20:26 2017-05-22-use-shield-to-backup-and-restore-redis.html.md
-rw-rw-r-- 1 eeyun eeyun 12K Jul 28 19:17 2017-05-23-Builder.html.md
-rw-rw-r-- 1 eeyun eeyun 4.2K Aug 16 20:26 2017-05-23-Scaffolding-App-From-Scratch.html.md
-rw-rw-r-- 1 eeyun eeyun 7.3K Jul 28 19:17 2017-05-23-Scaffolding.html.md
drwxrwxr-x 7 eeyun eeyun 4.0K Aug 16 20:26 media/
drwxrwxr-x 2 eeyun eeyun 4.0K Jul 28 19:17 partials/
... even more blog post files
Adding a New Post
Since the blog lives in the habitat mono-repo along with the website, adding a new blog post should feel just like contributing code! Start by creating your new blog post file alongside the other posts following the pattern {date}-{title}.html.md and fill that thing with all your glorious content.
$ vim habitat/www/source/blog/2017-10-01-Dank-New-Blogpost.html.md
The top of the 2017-10-01-Dank-New-Blogpost.html.md file is where we need to provide a tiny bit of metadata for middleman to render everything appropriately. So you’re going to want to add a header block to the file. The header block should include a date and title that match the filename, as well as any tags or category you want your blog to be attached to and a body-article flag.
---
title: Dank New Blogpost, Y'all!
date: 2017-10-01
author: New Blogger
tags: dankness, dankest, dankin-it-up
category: Community
classes: body-article
---
The last step here before you open your Pull Request, is to add in a bit more information around yourself as the author. After all it’s probably a good idea for you to get some credit for your work!
To do so, you’re going to need to add some information to one other file, our author_bios.yml file. Open and edit this file to make sure your author bio is populated at the end of your blog post:
$ vim habitat/www/data/author_bios.yml
---
authors:
ianhenry:
name: "Ian Henry"
email: "ian@chef.io"
twitter: "@eeyun___"
bio: "As the Technical Community Advocate for Habitat, Ian is actively helping the Community and ecosystem grow. He spends much of his time helping people learn about containerization, distributed systems, and the ways that Habitat makes those things easy. Prior to joining Chef, Ian spent a number of years as an operational and tooling engineer."
robbkidd:
name: "Robb Kidd"
email: "rkidd@chef.io"
bio: ""
fnichol:
name: "Fletcher Nichol"
email: "fnichol@habitat.sh"
twitter: "@fnichol"
bio: "Fletcher Nichol is a senior engineer who works on Habitat. He spends far too much time writing open source software and far too little playing the drums. In previous jobs he has been a web application developer, a systems administrator, and even an infrastructure-as-code koolaid barista."
new_blogger:
name: "New Blogger"
email: "blogist@bloggernator.net"
twitter: "@aintgotone"
bio: "New Blogger works for FOO company doing BAR engineering and in her freetime crushes out all sorts of other cool shit."
Note: The value of name: in the author_bios.yml should match the supplied name in the header of your blog post file.
After that, the only thing left to do is test your PR locally! Scroll on down to find an example of checking your change out. If you’ve verified everything looks/reads correctly, you are ready to fire off the PR of your new blog post. During code review, core maintainers will read your blog post and potentially ask you for changes if something might be misleading to the community. But, by and large, we’re pretty accepting of content and happy to help carry something if the author needs it.
Adding Media to a New Blog Entry
What happens if you need to do something like embed some images in your blog post? We’ve got you covered. You can definitely embed images from other websites with standard markdown syntax. However, you might have noticed a directory named media in habitat/www/source/blog/.
$ ls -l habitat/www/source/blog/media
drwxrwxr-x 7 eeyun eeyun 4.0K Aug 16 20:26 ./
drwxrwxr-x 4 eeyun eeyun 4.0K Aug 16 20:26 ../
drwxrwxr-x 2 eeyun eeyun 4.0K Jul 28 19:17 2017-05-23-Builder/
drwxrwxr-x 2 eeyun eeyun 4.0K Jul 28 19:17 2017-06-02-ChefConf/
drwxrwxr-x 2 eeyun eeyun 4.0K Jul 28 19:17 2017-06-28-Happy-Birthday-Habitat/
drwxrwxr-x 2 eeyun eeyun 4.0K Aug 16 20:26 2017-08-09-Fullfx/
drwxrwxr-x 2 eeyun eeyun 4.0K Aug 16 20:26 2017-08-11-Hab-and-Nginx/
Each of the entries in this directory are also directories and each of them have media meant to be embedded in various blog posts. Specifcally, media that isn’t being sourced from elsewhere on the internet. To add this type of media to your blog simply follow the pattern here. Create a directory and populate it with your media.
$ mkdir habitat/www/source/blog/media/2017-10-01-Dank-New-Blogpost
$ cp ~/downloads/superdopegif.gif habitat/www/source/blog/media/2017-10-01-Dank-New-Blogpost
Now superdopegif.gif can be referenced in your blog post file like so:
Note: Make sure when opening the PR for your blog post that you include all three of these changes so you don’t end up with images that are unable to render.
Testing your new blog post
Now that we’ve added in our custom media, our blog entry, and our author bio the only thing left to do before opening our PR is to test the change locally. We’ve tried to make this as simple as possible for anyone looking to contribute. Simply change directories into habitat/www and make run which will give you a live local example of the habitat site at http://127.0.0.1:4567
$ cd habitat/www
$ make run
Project built successfully.
bundle exec middleman serve
== The Middleman is loading
== Blog Sources: /blog/{year}-{month}-{day}-{title}.html (:prefix + :sources)
DEPRECATION WARNING on line 87 of habitat/www/source/stylesheets/vendor/foundation/components/_button-group.scss: #{} interpolation near operators will be simplified
in a future version of Sass. To preserve the current behavior, use quotes:
unquote('#{$buttongroup-spacing} == "0"')
You can use the sass-convert command to automatically fix most cases.
/usr/lib64/ruby/gems/2.2.0/gems/middleman-livereload-3.4.6/lib/middleman-livereload/reactor.rb:14: warning: toplevel constant Mutex referenced by Thread::Mutex
== LiveReload accepting connections from ws://192.168.1.6:35729
== View your site at "http://localhost:4567", "http://127.0.0.1:4567"
== Inspect your site configuration at "http://localhost:4567/__middleman", "http://127.0.0.1:4567/__middleman"
Once you’ve verified that everything looks and reads how you want it to, you’re ready to open your Pull Request!