Contributing To Tech Blog

Introduction

In 2016 we started a technical blog. We decided to keep it separated from the main site or institutional blog to avoid any possible conflict with marketing/PR/communication logic that could hinder the possibility, for every team member, to use his spare (or working) time to jot down a post on anything technical he found interesting.

Since static sites are all the rage now (and since it makes perfect sense they are :D) we based the blog on Hugo, a great SSG written in go. Portable, fast and very well documented, it supports Markdown for pages and posts, has themes and other amazing sweet things.

We also went with GitHub Pages and host the code of the blog on a public github project. The idea is to allow other contributors to fork the code and provide fixes, addenda or whole new guest articles.

There are no comments on the blog, we prefer to promote posts on socials and engage in discussion on them.

Folder structure

Despite you are engouraged to read Hugo documentation to learn how the system works, here is an overview of what you have in the project repo:

.
├── output
│   ├── 2016
│   ├── archive
│   ├── css
│   └── ... 
├── scripts
│   └── ... 
└── src
    ├── archetypes
    ├── content         <--- Content goes here
    │   ├── page
    │   └── post
    ├── data
    ├── layouts
    │   └── archive
    ├── public
    ├── static          <--- Assets (images, files) go here
    │   ├── img
    │   └── posts
    │       ├── 20170119-post-1
    │       ├── 20170321-post-2
    │       └── ...
    └── themes
        └── spark

The two location involved into posts/articles contributions are marked out.

  • src/content is where posts and pages markdown belongs. It is very uncommon to contribute new pages in our context, so this is out of the scope of this guide. The src/content/post folder is where you want to put your new masterpiece, generating a new file (will elaborate later on this).
  • src/static is the place to put any image, file, and binary that comes with your post. Having them here will allow you to reference and link them in your markdown; Hugo will then copy them in the right position when you regenerate the static site. Mind that src/static/img is used for the general layout assets: you have to store posts assets in a subfolder of src/static/posts, named like your post title to keep consistency (more information follows).

Preliminary steps

If you are working out your first contribution, you will have to add an Author biography entry to the src/config.toml file. The file content consists in a TOML header and a Markdown body. For some mysterious reason all go developers seem to be in love with TOML. You could actually use YAML instead, Hugo understand both. Anyway we kept the config file in standard format.

Back on track: you have to add an entry to the [Params.Authors] collection in the file, like this one:

    [Params.Authors.LeanJohn]
      name = "John Doe"
      role = "Lean Neveloper"
      picture = "http://www.sparkfabrik.com/images/team/leanjohn.png"
      bio = "Night rider, death dealer, storm bringer. Loves to quote Judas Priest songs. Blindly apply a make it 'till you fake it attitude."
      github = "http://www.github.com/leanjohn"
      twitter = "http://www.twitter.com/leanjohn"

Please, substitute the clearly fake data above with your (hopefully) serious ones.

ATTOW you also have to add your data to the src/content/page/team.md file. Despite its extension this file mostly contains pure HTML and is totally static, reason why you have to manually add an entry to it (improvements on this are really welcome).

You will have to add a code block before the closing </div> tag. Places where your data go are marked out with {{ fake text }} in the code below. Please get rid of all, curly braces included, and put actual data in place.

If you are contributing an article on our blog this is not supposed to be difficult! ;)

<div class="row row-top-margin">
  <div class="col-md-12">
    <h4>{{ John Doe }}</h4>
    <img src="http://www.sparkfabrik.com/images/team/{{ leanjohn }}.jpg" alt="{{ John Doe }}" class="img-rounded pull-left avatar">
    <i>{{ Lean Neveloper }}</i>
    <p class="small">{{ Night rider, death dealer, storm bringer. Loves to quote Judas Priest songs. Blindly follows the make it 'till you fake it philosophy }}</p>
    <ul class="list-inline">
      <li> <i class="fa fa-github"></i> <a href="http://www.github.com/{{ leanjohn }}">Github</a> </li>
      <li> <i class="fa fa-twitter"></i> <a href="http://www.twitter.com/{{ leanjohn }}">Twitter</a> </li>
    </ul>
  </div>
</div>

Check your changes locally loading http://tech.sparkfabrik.loc/page/team/.

Writing an article

You are now ready to conquer the web with your knowledge and verve.

Create post file

Add a markdown file in src/content/post. The file name must match this format

YYYYMMDD_title_slug.md

where, needles to say, YYYYMMDD is the reverse date format the post is written. Mind that you can take a while to finish your post or, maybe, we can agree a delayed publishing, for example if a teammate just published a new post and publishing another one would lower the visibility of both... well, anyway be prepared to fix the filename before it can be merged in production.

Add the post header to the file

Here is a sample conventional code you must adhere to:

  1 +++
  2 date = "2017-03-04T14:47:30Z"
  3 draft = false
  4 title = "A wonderful new post - Jurney to the fame and back"
  5 description = "An experiment on becoming famous saying almost nothing. With PHP. And cookies."
  6 tags        = [ "php", "fake", "cookies", "fame" ]
  7 topics      = [ "PHP", "Fake stuff", "Biscuits" ]
  8 author = "LeanJohn"
  9 +++

Again this is TOML but you can use YAML also, just use minus signs instead of plus to mark header start and finish section.

Some of the lines above are very important:

  • date must be set to the publication date, so your new article appears atop the older ones. This should ideally match the file name (as described above), so it will be the last thing you'll edit before the contribution will be accepted and merged into release branch.
  • draft controls if the article is visible in production. Since we don't go to production until the post is approved and merged you'll probably keep this set to false even while working it out. Still it can be useful to control a flow of pre-written publications, already merged in production.
  • title and description have to be set so page title, post title and other metadata are set for search engine and for the user who stumble upon a link to your piece.
  • author must match the key of your [Params.Authors] entry in config.toml (see above). In our example we used [Params.Authors.LeanJohn] as a key, so we kept the example consistent.
  • tags and topics are other metadata that currently have no effect from a user perspective. Use them at your own discretion; if in doubt spy what your mates have done in other posts and keep things consistent.

Add your post text

Under that block, please add your markdown as you normally would with any other md-based product, but beware that since an h1 is used to print the page title by Hugo, your document sections hierarchy must start from h2, so your first-level titles should be like:

## My title

Text text text ...

## Let's move on

More more text ...

### Subchapter

Moving to a new level

### Another subchapter

Is nice to stay at level 3...

## Closing thoughts

This text closes my thoughts

One more thing to take into account is how to link assets (images etc). As already told you have to place your post assets in src/static/posts/your-article-title. To reference them in your markdown you can than build a relative URI like /posts/your-article-title/awesome-image.png.

To use an image for example you will want to insert

![This is an awesome alt text](/posts/your-article-title/awesome-image.png)

Peer-review workflow

We are using the typical GitHub contribution flow, based on pull requests, so:

  • Fork the repo on your private account
  • Work your post out on either dev branch or a feature branch, as you see fit
  • Before sending a PR, fetch upstream and rebase your work upon a fresh dev
  • Send a PR when your post is done and address any possible feedback

Deploy occurs automatically on PR merge, so sit back and enjoy fame.

NOTE: a quick checklist is availabe at Recipes / Tech Blog Checklist page.

External contributions

In case you are reading this and want to contribute fixes or addenda to a present article, all the above apply, but keep in mind you should credit yourself for you contribution. A good format is this:

**EDIT**

Here is a valuable contribution to this post, so that I can fix a misleading and outdated information.

*Contributed by [@yourNick](link what you want) on DD/MM/YYYY.*

**END EDIT**

Please, keep European date format in the last line.

If you want to contribute a guest article, please contact us so we can work out a solution to add your bio, without having it on the team page.

Last updated on 2018-11-23T16:08:06+00:00