Skip to content

Home

Jump to bottom
Chris McKelt edited this page Feb 2, 2021 · 1 revision

Introduction

This project is based upon the 'Jekyll' website generator. Using this project, you can create minimal, static, blog style posts using only the Markdown format.

This project has been configured to serve these posts under the URL https://takesinsight.com

Creating a post

Before publishing our content to the world, we may make several iterations and get collaboration from others. Follow these steps

  1. clone the repository locally
  2. create a branch with your post name eg posts/2021-02-01-azure-blah-blah
  3. write your post!
  4. add images to the /assets/images folder and reference in your post e.g. <img src="/assets/images/your-title/your-image.png">
  5. put up a PR back to main branch
  6. confirm the format looks good by going to your GitHub pull request and viewing your new .md file online
  7. request teammates to review your post.
  8. push any requested changes to the branch which will update the PR
  9. merge to publish your post and view on takesinsight.com

Posts are authored in markdown and must have the .md file extension. Jekyll automatically finds and list our files based the filename. Files must use the following naming convention:

YYYY-MM-DD-title.md

i.e. 2021-02-01-first-post.md

Tips

  1. Dont work directly on main and be aware of GitHub Pages limits.
  2. There is a soft limit of 10 builds per hour. If you exceed this, your content may not be visible. Full usage limits are available at docs.github.com/.../about-github-pages
  3. Ensure your name is in the authors list
  4. Have a look at existing posts in the _posts folder for examples

Post Content

Jekyll files start with Front Matter. This is a YAML block that tells Jekyll about our file. At minimum, you post should include the below Front Matter.

---
layout: post
title: 'Your groovy title'
category: posts
author: your author name (see authors.yaml) e.g. psmithdale
tags: put in category tags for users to filter on. e.g. azure cosmosdb (or make a new one)
---

More information on Front Matter can be found here

Markdown

Please refer to the Markdown guide hosted at https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet to see an example of permitted markup.

Use of headers

To ensure correct structure of your post, consider the following header recommendations.

  • Site Title: uses H1 #
  • Post Title: uses H2 ##
  • Your post sections should use H3 ### and below

Update this wiki to help others.

Happy blogging!

Clone this wiki locally