Hugo - Content - Markdown

   
   
 hugo  sass  
 ssg  frontend  
Article Series

This article series contain few sections.

Supplementary Article for Windows User.

Clone Tutorial Source.

Where to Discuss?

Local Group

Table of Content

Preface

Goal: Common use of markdown in Hugo content

There is not much to say about markdown. Markdown is easy, however there might be a tricky issue.

Reading

Why Markdown?

More on Writing Content

While markup focus on document formatting, markdown focus on document structure.

1: Split Resource

It is a good practice to split resource and content.

Common Structure

The common structure for content in Hugo are:

  1. Frontmatter: YAML, TOML or JSON

  2. Content: Markdown or HTML

Th combination is all up to you, your choice, to manage your content.

Real Life Structure

I think that easier just to live with this structure, split the content, and the resource (link and image).

  1. Frontmatter: YAML or TOML

  2. Content: Markdown

  3. Resource: Markdown

+++
type       = "post"
+++

# Header 1

My content

[My Link][my-image]

-- -- --

## Header 1.1

My sub content

![My Image][mylink]

-- -- --

## Header 1.2

My other sub content

[//]: <> ( -- -- -- links below -- -- -- )

[my-image]:    http://some.site/an-image.jpg
[my-link]:     http://some.site/an-article.html

Notice, that the markdown divided into two part by using

[//]: <> ()

Shortcode Issue

The issue is, Hugo does not allow any Chroma code in markdown content. But Hugo can utilize shortcode in markdown content

BaseURL

Consider create shortcodes

{{- .Page.Site.BaseURL -}}

Now we can use the baseurl shortcode, to solve link issue.

[local-whats-next]: {{ < baseurl > }}quotes/2018/09/07/julian-baker-something/

And call the link later in markdown format.

### What's next ?

Our next song would be [Julian Baker][local-whats-next]

I often use shortcodes for reccuring link. For example for my blog, I use dotfiles a lot.

Consider create shortcodes for dotfiles.

{{- "https://gitlab.com/epsi-rns/dotfiles/tree/master" -}}

Again, we can use the baseurl shortcode, to solve recurring link issue.

[link-dotfiles]:    {{ < dotfiles > }}/terminal/vimrc/vimrc.bandithijo

And call the link later in markdown format.

### Example Dotfiles

ViM RC: [bandithijo][link-dotfiles]

3: Shortcode: Image

Prepare Image Directory

It is, a good practice to have a good structured directory. Just put all your resources in assets directory. And how you structure you image, javascript, vector and such, is actually up to you.

I respect copyright, so I put my own old photographs, as an example.

Hugo Content: Image Directory

Other example might be as complex as: using section, categories, year and month.

  • static/assets/posts/ssg/2018/11/thunar-03.png

Again, now we can use the baseurl shortcode, to solve image link issue.

[image-kiddo]:    {{ < baseurl > }}assets/posts/2018/kiddo-007.jpg

And show image later in markdown format.

![A Thinking Kiddo][image-kiddo]

4: Responsive: Image

We are not finished yet. We need the image to shrink the image, so it always follow the size of the container.

Layouts: Single

Remember our previous single.html.

        <article class="main-content" itemprop="articleBody">
          {{ .Content }}
        </article>

We have already had a class called main-content.

SASS: Content

Now we can implement a bootstrap mixin in this content:

.main-content img {
    @include img-fluid;
}

SASS: Main

  // variables
    "bootstrap/mixins/image",

  // custom
    "content"

And the complete SASS is here

@import
  // taken from bootstrap
    "sticky-footer-navbar",
    "blog",
    "bootstrap-custom",

  // variables
    "bootstrap/functions",
    "variables",
    "bootstrap/variables",
    "bootstrap/mixins/breakpoints",
    "bootstrap/mixins/image",

  // custom
    "layout",
    "decoration",
    "list",
    "pagination",
    "post-navigation",
    "content"
;

5: Summary

Example Content

Consider have a look at one of our song quotes, written in markdown.

+++
type       = "post"
title      = "John Mayer - Slow Dancing in a Burning Room"
date       = 2018-02-15T07:35:05+07:00
categories = ["lyric"]
tags       = ["rock", "2010s"]
slug       = "john-mayer-slow-dancing-in-a-burning-room"
author     = "epsi"
+++

We're going down.
And you can see it, too.

We're going down.
And you know that we're doomed.

My dear, we're slow dancing in a burning room.

![A Thinking Kiddo][image-kiddo]

-- -- --

### Example Dotfiles

ViM RC: [bandithijo][link-dotfiles]

-- -- --

### What's next ?

Our next song would be [Julian Baker][local-whats-next]

[//]: <> ( -- -- -- links below -- -- -- )

[image-kiddo]:      {{ < baseurl > }}assets/posts/2018/kiddo-007.jpg

[local-whats-next]: {{ < baseurl > }}quotes/2018/09/07/julian-baker-something/
[link-dotfiles]:    {{ < dotfiles > }}/terminal/vimrc/vimrc.bandithijo

Hugo Content: Shortcode Example: Link and Image

What is Next ?

There are, some interesting topic for using HTML in Hugo Content, such as inserting Table of Content. Consider continue reading [ Hugo - Table of Content ].

Thank you for reading.