Hugo Markdown Intro

Introduction

This website is made with Hugo and hosted on Gitlab, Hugo is a static site generator written in Go and Gitlab is used to keep versioning of the code/file of my website ( like an external backup with history of all my modification ).

I’m using as well the GitLab CI/CD to deploy/build and test automatically my website once I commit my code change. It’s one of the reason I have chosen Gitlab instead of GitHub

I have chosen Hugo because it’s made with Go language and Go is very efficient and fast and i ❤️ it.

Hugo Logo

New version of Hugo is using the GoldMark Markdown Parser written in Pure go and which is easy to extend, Standard-compliant and well-structured.

Basically, the GoldMark Markdown will provide your short-code or shortcut to write your post without using HTML Markdown is intended to be easy-to-read and easy-to-write. Markdown is a text-to-HTML conversion tool.

This article is a brief overview about the GoldMark Markdown used to make easy post without writing any HTML.

Markdown will give you the possibility to write post even if you do not have any knowledge of HTML and you will write your posts faster.

You can still used HTML if you prefer and i’m using it for the images as it’s more configurable, Markdown has from now few limitation. It’s recommended to let blank line between Markdown and HTML Tags.

I never say NO for gaining few time !

Basic Syntax

Let’s start by the beginning.

Heading

To create a heading, it’s very easy ! Just add # in front of a word or phrase and the number of # you will use should correspond to the heading level.

Use by example 3 # if you want heading level 3 (H3)

For compatibility, always put a space between the # and the word.

# H1
## H2
### H3
#### H4
##### H5
###### H6

Paragraphs

It’s easy to create paragraphs, just use a blank line to separate one or more lines of text.

this is the first line
this is the second line

this is the first line this is the second line

For example, to add an HTML Table to a Markdown article

This is a table in paragraph made with Markdown.

This is HTML table

<table>
    <tr>
        <td>Yeah !</td>
    </tr>
</table>

Wow it works great !

Line Breaks

To create a line break <br>, end a line with two or more spaces, and then type return. Easy, isn’t it ?

Escaping Characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash \ in front of the character.

By example, if you want to write the char (#) :

\#

Bold and Italic

Bold

To bold text, add two asterisks or underscores before and after a word or phrase.

To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.

Example :

I love **Git** and I love __automation__

I love GIT and I love automation

Italic

To Italic text, add one asterisk or underscore before and after a word or phrase.

Example :

I love *Powershell* and _python_ , am i a geek ?

I love Powershell and I love python

Both Bold and Italic

To Bold and Italic text, add 3 asterisk or underscore before and after a word or phrase. Make sense ? Huh ? In this case, it’s better to use Asterisk than underscore to avoid any issue.

Example :

I love ***Food*** !

I love Food !

Strikethrough

You can strikethrough words by putting 2 tilde char before and after the word . The result looks ~~like this~~

⚠️ For mac, the tilde is made with this combination : Option + N

Horizontal Rules

To create a horizontal rule, use three or more asterisks (***), dashes (—), or underscores (___) on a line by themselves.

***

Blockquotes

To create a blockquote, add a > in front of a paragraph.

> Keep It Simple

Keep It Simple

Blockquotes with Multiple Paragraphs and other MarkDown

> Working in IT is a **challenge** 
>
> *Challenge* is to keep learning and keep being passionate about new technology. Keep going !

Working in IT is a challenge

Challenge is to keep learning and keep being passionate about new technology. Keep going !

Lists

Ordered Lists

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

1. First item
2. Second item
3. Third item
4. Fourth item

First item
Second item
Third item
Fourth item

Unordered Lists

To create an unordered list, add dashes -, asterisks *, or plus signs + in front of line items. Indent one or more items to create a nested list.

- First item
- Second item
  - First item
  - Second item
- Third item
- Fourth item

First item
Second item
- First item
- Second item
Third item
Fourth item

Easier and faster than HTML, no ?

<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item
<ul>
<li>Indented item</li>
<li>Indented item</li>
</ul>
</li>
<li>Fourth item</li>
</ul>

Task Lists

Task lists allow you to create a list of items with checkboxes. In Markdown applications that support task lists, checkboxes will be displayed next to the content. To create a task list, add dashes (-) and brackets with a space ([ ]) in front of task list items. To select a checkbox, add an x in between the brackets ([x]).

- [x] Stop Smoking
- [ ] Stay less on computer
- [ ] Go more outside

Stop Smoking
Stay less on computer
Go more outside

Table

To add a table, use three or more hyphens (—) to create each column’s header, and use pipes (|) to separate each column. You can optionally add pipes on either end of the table.

You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags in table.

| Name     | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

Name	Description
Header	Title
Paragraph	Text

Alternatively, to go faster you can use this table generator https://www.tablesgenerator.com/markdown_tables

Image

To add an image, add an exclamation mark (!), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses.

 ![This is the ALT of the image](../../img/cloud.png)

This is the ALT of the image

The source will be different follow your configuration.

Code Block and Syntax highlighting

For Code block, use three char ` before and after your code and use the language used. I’m fan on this !

```json {

“firstName”: “John”,

“lastName”: “Smith”,

“age”: 25

} ```

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

URL - Links

By default, The URL linking are automatic. If you want to disable the link, use the code char ` before and after the url

\`http://www.awesomewebsite.com`

The rendered output looks like this:

http://www.awesomewebsite.com

If you want to change the title for the link, use this syntax :

[Linkedin](https://www.linkedin.com/in/julien-simon-66030665/)

⚠️ For compatibility, It’s recommend to replace space on the link by %20

Internal Links - Anchor

The best way i find to make internal link or anchor inside a post is a follow :

Add an internal link with HTML after an header as below

## Past life <a name="nameanchor"></a>

Past life

And add a new link as below inside your post, then you can click on the link to jump on the title

[Jump to Childhood](#nameanchor)

Jump to Childhood

Emoji

In most cases, you can simply copy an emoji from a source like https://emojipedia.org/ and paste it into your document.

Some Markdown applications allow you to insert emoji by typing emoji shortcodes. These begin and end with a colon and include the name of an emoji.

Working! (💻) Be back soon.
Love it! (❤️)

Working! 💻 Be back soon. Love it! ❤️

To add fancy emojis to your file, click control+cmd+space on your Mac and choose your emojis.

Jump to the beginning

Conclusion

Markdown is definitively a great tool and it will let you gain a lot of times when you will be used to. It’s still new for me but i’m happy to use mostly Markdown instead of any HTML tags.

So practice and have fun !