Learn and Discover Open Source with Daily Genuine Experience. From Coding, Front End, Back End, Database, and Static Site Generator.
 
 


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.

Table of Content

  • Preface: Table of Content

  • 1: Split Resource

  • 2: Shortcode: Link

  • 3: Shortcode: Image

  • 4: Responsive: Image

  • 5: Summary

  • What is Next ?


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.