BLOG-POST-TEMPLATE.md

title	date	images	category	tag	authors
Blog Post Template	2023-10-19	/images/2023/10/image.png	Templates Examples	Getting Started Tutorials	Christopher Luna Kevin Centeno

This is a blog post template that you can use to create new blog posts. Copy and paste the contents into a new file to get started.

If you're reading this file through the GitHub user interface, you may see it rendered. That's because GitHub also renders markdown files for documentation. If you want to see how the file is written, you can click the "Raw" button to the upper-right to see the markdown syntax.

Read on to learn more about formatting, options, and behavior below:

• how to create a new blog post
• understanding the blog head where organizational parameters are defined
• formatting copy with markdown
• embedding images in your blog post

If you're interested in learning about how the blog generates metadata for SEO purposes, you can read more below.

Creating a New Blog Post

To get started, make a new file. The file should be located in the following directory:

/content/<YYYY>/<MM>

For example, if this was a real blog post, written on October 19, 2023, I would put it in:

/content/2023/10

The file should be named as follows:

<Desired URL Path>.md

For example, if this was a real blog post, it would have the following path:

https://blog.maxmind.com/2023/10/BLOG-POST-TEMPLATE

Generally, you should choose a file name that contains only lowercase letters, numbers, and hyphens.

For SEO purposes, it's good for this file name to be the same as the title of the blog post.

Once you have the file created, you can paste the contents of this template into the new file and begin to modify it.

Blog Head

The head of each blog post is at the very top of the file. A line with three hyphens opens and closes the header, as you can see above.

Some attributes take an unordered list, which is part of the basic markdown syntax.

The head contains the following attributes:

Attribute	Description
title	The title of the blog post, contained in double quotes (""). This will be used both as the title displayed at the top of the post in a level 1 header, and as the <title></title> meta tag. Learn more about metadata on the blog.
heading	The heading for the blog post, contained in double quotes (""). This will be used as only the title displayed at the top of the post in a level 1 header. If this is omitted, then the title will be used as the level 1 header. Note: The <title></title> meta tag will still be the title. This is optional and should only be added if you want the metadata and h1 tag on the page to differ.
description	The description of the post, contained in double quotes (""). This is optional.
date	The date that the blog post is published in YYY-MM-DD format. Should be contained in double quotes ("").
images	The unordered list of paths to the featured image(s) of the post. The first image is displayed on the blog home, and all images are used for social sharing. Learn more about images below.
category	The list of categories for the post, each contained in double quotes (""). You can use any strings you want, so you need to manually ensure that your categories are spelled the way you'd like and are consistent with other posts.
tag	The list of tags for the post, each contained in double quotes (""). You can use any strings you want, so you need to manually ensure that your tags are spelled the way you'd like and are consistent with other posts.
authors	The list of authors for the post, each contained in double quotes (""). Only the first author is displayed.
slug	This will override the automatically generated slug of the post YYYY/MM/DD/name-of-the-file will now become YYYY/MM/DD/specified-slug-name. Should be contained in double quotes ("").
url	This will override the automatically generated url of the post YYYY/MM/DD/name-of-the-file will now be specified-url-name. Should be contained in double quotes ("").

Markdown

Posts are written in markdown, a simple markup language. Not all features of markdown will be available to the blog, but basic things like unordered lists and, for example:

• links,
• basic formatting for text, including
  • bold,
  • italics, and
  • inline code

are all supported. There are also ordered lists, and markdown from the extended syntax, for example:

1. All the items in this after this one are anchor links to sections,
2. which are organized with headers.
3. Headers can be given custom IDs for anchor links to point to.
4. You can embed images in the blog.
5. You can make code blocks.
6. You can make tables.

Headers in Markdown

Headers in markdown are easy to write. They're prefixed by some number of "pound" glyphs (#). The number of #s defines the level of the header, for example ## followed by text would be a level 2 header, or ### followed by text would be a level 3 header, like the header directly above this paragraph.

Custom IDs for Anchor Links

If you want to make links to your headers, you can create custom IDs that can be used in links. To do this, add something like {#anchors} after a header to allow you to link to that header.

These custom IDs don't render properly in GitHub's markdown, but they do work in the blog's markdown. If you wanted to make the header directly above this paragraph have the custom ID of anchors so that links pointing to #anchors will hit the header in question, you would write the header as follows:

### Custom IDs for Anchor Links {#anchors}

If you don't define a custom ID, the header will automatically have an ID that is a simple transformation of the text of the header. For example, the ID of the header for this section is custom-ids-for-anchor-links. The text is transformed to all lowercase, special characters are ignored, and spaces are turned into hyphens.

Content Summaries

You can define a summary manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. To manually set a summary for a blog post, see https://gohugo.io/content-management/summaries/.

Internal Links and Shortcodes

Using relative links and shortcodes to refer to other pages is strongly encouraged instead of hardcoding paths. Hugo emits an error or warning if a document cannot be uniquely resolved. See https://gohugo.io/content-management/cross-references/ for how to utilize the shortcodes.

For example:

Don't do this:

[Discontinuation of the GeoLite Legacy Databases](/2018/01/discontinuation-of-the-geolite-legacy-databases/)

Do this:

[Discontinuation of the GeoLite Legacy
Databases]({{< relref "2018/01/discontinuation-of-the-geolite-legacy-databases.md" >}})

Images

In markdown, you can embed images with the following format:

![alt-text](path/to/image)

The image above won't actually display properly, because you also need to add your image to the correct location and use the proper path.

Images should be added to the blog in the following directory:

content/static/images/YYYY/MM

For example, if this was a real blog post I would add any images to the following directory:

/content/static/images/2023/10

Featured images, which are defined in the blog post head, should be added to the same directory.

The blog can render jpg, png, and svg images. The images will be rendered horizontally-centered with the copy of the blog post.

Code Blocks

Inline code is marked with a single opening and closing backtick (`), as in inline code, for example. This renders the text with monospace font and subtle styling differences to indicate that you're looking at code.

Often in a technical blog we may need to share more code. For that we use code blocks, which are marked with three backticks followed by the code language to open the block (for example, ```bash). To close a code block, just put three backticks by themselves on their own line. For example:

here's what it looks like to make a code block
none of this is real code
but at least it will be displayed as if it is ...

Tables

You can even make tables in markdown, and they even kind of look like tables in the text. It's easier to just show you how to make a table than to explain:

Header Column 1	Header Column 2	Header Column 3
Row 1 Column 1	Row 1 Column 2	Row 1 Column 3
Row 2 Column 1	Row 2 Column 2	Row 2 Column 3

If you want an easier way to make tables in markdown, you can also try this Tables Generator.

Metadata

We can use OpenGraph meta tags for social sharing. Hugo has an embedded OpenGraph template: https://gohugo.io/templates/embedded/#open-graph. Hugo OpenGraph embedded template source code.

At this time, the blog generates metadata in the following ways:

• The title parameter in the blog post head generates the <title></title> tag
• The meta description in the blog post head is generated by the description in the blog post head. If no description is set in the front matter of the post, there will not be a meta description tag.
• OpenGraph meta tags:
  • og:title is populated with the title parameter in the blog post head
  • og:description is populated with the description parameter in the blog post head. If no description is specified, this will default with the first paragraph of the post.
  • og:site_name is MaxMind, which is the title set in config.toml
  • og:locale is en_us, which is the languageCode set in config.toml. (- is replaced with _.)
  • og:audio is populated with a list of audio paths
  • og:video is populated with a list of video paths
  • og:type is populated with the value "article"
  • og:url is populated with the URL of the article, which is derived from its path and filename
  • og:image is populated with the images parameter in the blog post head
  • article:section is populated with the year of the post from the date parameter in the blog post head
  • article:published_time is populated with the timestamp of midnight on the date specified in the date parameter in the blog post head
  • article:modified_time is populated with the timestamp of midnight on the date specified in the date parameter in the blog post head

Redirects and Aliases

You can use Hugo's Aliases to create redirects from old URLs to new URLs.

For example, you would change the new file name and make the alias the old file name:

aliases:
['2024/06/maxmind-appoints-seasoned-data-science-leader-rupert-young-as-chief-product-officer.md']