Authoring and editing articles for our blog works by creating simple text files. Well, it’s not exactly as simple as that, which is why you’re here to learn how it’s supposed to work, right? :)

We’re going through the minimal workflow first, and then discuss more advanced topics like embedding images or other resources.

If anything doesn’t work, please ask for help at our Slack or GitHub! You can also find some help in the official Hugo documentation, which is our website generator.

Where to Start

Log in to GitHub if you’re not already authenticated. Open the blog’s source repository at

Creating a New Article

Navigate to the hugo/content/post subdirectory, where you can Add file -> Create new file:

Add file

Enter a new name for a new subdirectory, then a slash /, then The subdirectory helps to organize your article along with its resources like images or downloads. The subdirectory name should contain only lowercase letters and dashes “-”.


Then you can enter the article content. Some metadata, so-called frontmatter, is necessary for seamless integration in our framework. The frontmatter is surrounded with triple --- and consists of several fields like the article title and a short description:

Add article content

We’ll go into detail about the frontmatter later.

You should use Markdown syntax, and you can use the Preview button above the content to get a basic impression of your article. If you want to learn Markdown, there’s an interactive tutorial at to learn everything you need.

When you’re happy with your article and want to save it, please scroll down to the Commit new file section. Some defaults are already provided. Please ensure that you select Create a new branch for this commit … before you click on Propose a new file. If creating a new branch isn’t available for you, please select Fork….

Images and Downloads

You can use publicly available images from a service like Unsplash to spice up your article. If you want to use your own images or don’t want to use external links, you’ll have to upload them to this repository first.

We’ll show you both options, starting with the easiest one.

Hint: you can use an image as feature_image in your article’s frontmatter. Those images will be used in lists and as header image of our articles.

Adding Images and Downloads

Including images via Markdown syntax is the easiest way by copying the image url and wrapping it in those beautiful brackets:


If you need a clickable image you’ll have to use even more of those beautiful brackets. The following example shows you how you can redirect users to another document, an image with better resolution, or to another website:


The result looks like this:

Image “white ceramic mug on table” by Danielle MacInnes

Uploading Own Resources

Images can be huge and contribute most to the required bandwidth of our website’s visitors. Hugo can help to reduce the image size by preprocessing images. That doesn’t work completely transparent for us, though, because we have to download the image and save it along with the article in our repository. We also have to replace Markdown syntax with a dedicated Hugo syntax.

This part of our guide has not been finished, yet. Please contact a Codeowner or leave a comment in your pull request.

Hugo’s figure Shortcode

The special syntax uses a so-called shortcode and gives us some additional features.

Let’s look at an example like this written in Markdown:

![Benjamin Franklin Book](photo-1499080863200-1f37ed9cb653.jpeg)

We should change it to the following shortcode:

{{< figure src="photo-1499080863200-1f37ed9cb653.jpeg"
        caption="Benjamin Franklin Book"
        attr="Photo by Mona Eendra"
        attrlink="" >}}

As you see, we didn’t only set the src parameter with our image filename, but added some attribution to give the photograph their credit.

The result will look like this:

Benjamin Franklin Book

Benjamin Franklin Book Photo by Mona Eendra

Several options are available, like width and height. You can find more details in the documentation for Hugo’s Shortcodes.

Previews, Reviews, and Publishing

Nobody is perfect - which is why we rely on reviews before publishing content. Your article is now available for others to leave comments and find your little typos.

Reviewing the plain Markdown text is only one option. If you look closely at the end of your pull request, you’ll see an area with several checks by the Netlify platform. Apart from the sanity checks, Netlify provides a true preview of your article at Details as soon as the checks tells you “Deploy preview ready!”:

Deploy preview

Reviewers will give you feedback and can give suggestions for improved wording. When your article is deemed to be ready, you can merge your article to the mainline, which kicks off the automated process to generate an updated version of our blog with your article:

Merge and Publish

Great job!