GitHub Twitter Slack

# Blog Posts

The BlogIndex component renders blog posts. By default, it will process all pages located underneath /blog/, and will display a section for each post with a preview which is generated from the posts excerpt. Posts will be ordered by date with the more recent posts naturally listed first.

# Format

A simple example of a blog post would be this:

<!-- blog-post-example.md -->
---
date: 2019-08-09
---

# Version x.y.z brings this New Cool Feature

This section will be rendered as an excerpt in the preview of the blog post.

<!-- more -->

## Dive into details here

Everything below the above comment line will not be rendered in the preview, but
will be displayed perfectly fine on the details view of your blog post.

There are a few things to know about writing blog posts, all of which you can see in the example above:

  • A posts date is solely defined by the frontmatter (opens new window) parameter date. This is the only frontmatter data the BlogIndex component requires. The date format is YYYY-MM-DD.
  • The blog post title is derived from the h1 header as provided in the blog post markdown page. You don't have to provide a title in frontmatter. You can though, in case you want to specify a blog post title different from the page title.
  • BlogIndex will render an excerpt for each post that provides it. You can define an excerpt by simply adding an html comment that says more below the section that should be rendered as an excerpt.

TIP

The excerpt should focus on the gist of the message, and not contain repetitive phrases that don't add much value. Prefer KUDO x.y.z brings this New Cool Feature over "we are proud to announce version x.y.z".

In order to keep previews slim, any headers within the excerpt will be hidden, and paragraphs will be changed to spans.

# Naming Convention

Posts will be sorted according to their date. In order to find easily tell apart release announcements from other posts, please follow the following naming convention:

  • Release announcements: announcing-kudo-<version>.md
  • Other blog posts: blog-YYYY-MM-<name>.md

# Release Posts

A blog post that notifies of a release should follow this format:

  • The title should be Announcing KUDO x.y.z
  • The first paragraph should summarize the high level additions in this release and must be followed by an html comment line:
    <!-- more -->
    This will use this forst paragraph as an excerpt for rendering the blog posts overview and rss feed summary.
  • The following content should be copied/pasted from the Github release page
  • The blog post should close with a link to the changelog and ideally an overview of the next release.

You can find a template here (opens new window).

Link Your Post

We haven't added a dynamic sidebar yet so each blog post must be manually added to the blog section of the sidebar in config.js (opens new window).

# Authors

We want to make contributions more personal, especially for blog posts and probably even for release announcements. In order to render the author of a blog post, please follow a few simple steps:

# Add Author Metadata

Add metadata about the author to authors.md (opens new window). A simple example would be

{
  "alias": "meichstedt",
  "name": "Matthias",
  "about": "Matthias is mostly harmless.",
  "avatar": "meichstedt_200x200.jpg"
}

The full list of possible properties is as follows:

alias

The authors GitHub alias, and the ID for looking up authors in this documentation. If no alias is given, all authors will be rendered.

name

The authors full name (or whatever they want to have displayed).

about

Some information about the author which will be in a about the author section.

avatar

(optional) The filename of the author's image which needs to be provided in /authors (opens new window)

twitter

(optional) The author's twitter alias.

# Add An Image

If you want to render an image using the avatar property, add it to the authors (opens new window) folder. Images should ideally be 200x200 pixels.

# Reference The Author

Finally, reference the author using the given alias at the and of your blog post like so:

<Authors alias="meichstedt" />

You can see how this will render at the end of this page.

Matthias About the author
Matthias is fueled by bitter-sweet coffee, mostly harmless, and manages the Orchestration team at D2iQ whenever he's not fiddling with the KUDO site or trying to make his Andalusian Hounds behave like proper dogs. Find Matthias on GitHub (opens new window)

← Custom Badge →