Hexo - Content - Markdown

Preface

Goal: Common use of markdown in Hexo content

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

Reading

• daringfireball.net markdown syntax

Why Markdown?

More on Writing Content

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

Source Code

You can download the source code of this article here.

• hexo-ejs-bulma-tutor-05-content.zip

Extract and run on CLI using $ npm install.

0: Markdown Content

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 Hexo are:

1. Frontmatter: YAML, 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 JSON

2. Content: Markdown

3. Resource: Markdown

---
layout    : page
---

# 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

[//]: <> ()

2: Line Break

Hexo markdown treated each line as newline. Differently with standard markdown that require explicit backslash to make a new line break. This could make your life hard.

Content: Post

As usual, we require example content.

• source/_posts/white-winter.md

  gitlab.com/…/source/_posts/white-winter.md

---
layout    : page
title     : Surviving White Winter
date      : 2016/11/13 11:02:00
---

It was a frozen winter in cold war era.
<!-- more --> 
We were two lazy men, a sleepy boy, two long haired women,
a husky with attitude, and two shotguns.
After three weeks, we finally figure out, about **css framework**.

But we lost our beloved husky before we finally made it.
Now, every january, we remember our husky,
that helped all of us to survive.

Render: With Issue

This will result as:

Configuration

You can standarize using this, to disable this unused newline feature

• _config.yml

  gitlab.com/…/_config.yml

# Markdown
marked:
  gfm: true
  breaks: false

Remove db.json, and restart server.

Sass

Now you still need to different between paragraph and newline:

• themes/tutor-05/sass/css/_post-content.scss

  gitlab.com/…/sass/_post-content.scss.

.blog-post p
  margin-top: 0.5rem
  margin-bottom: 0.5rem

Render: Without Issue

This will result as:

We have nomore line break issue.

3: Heading Title

Markdown Render

Normally markdown render this:

# My Heading Title

Into this:

<h1>My Heading Title</h1>

Bulma Class Issue

Bulma require heading title to be written as this below:

<h1 class="title is-1">My Heading Title</h1>

Otherwise, heading title rendered without proper size. This means your heading would not be rendered correctly.

Content: Post

Again, content for example purpose:

• /source/_posts/lyrics/david-gates-lady-valentine.md

  gitlab.com/…/source/…-lady-valentine.md

---
title     : David Gates - Lady Valentine
date      : 2014/03/25 07:35:05
tags      : [jazz, 80s]
category  : [lyric]
---

She's a real look  
cause she's my heart my inspiration  
Lucky is the man who find the child of love

<!-- more --> 

# Heading 1

## Heading 2

### Example Content

Your the music your my song  
Here with me is where you belong

Your the rythm, your my ryhme  
Keep me right into the time  
And I'm so happy when you're here

The figure above show that all heading rendered with the same size.

Custom SASS: Heading

We can fix the title heading by this SASS.

• themes/tutor-05/sass/css/_post-title.scss

  gitlab.com/…/sass/_post-title.scss.

h1
  font-size: $size-2

h2
  font-size: $size-3

h3
  font-size: $size-4

h4
  font-size: $size-5

h5
  font-size: $size-6

h6
  font-size: $size-7

h1, h2, h3, h4, h5, h6
  font-weight: $weight-semibold

And the result is prettier now.

4: Link and Image

There are two methods to provide link and image in Hexo. But still, I cannot find an easy way to make things simpler in Hexo.

Content: Pure Markdown

Again, content for example purpose

• /source/_posts/lyrics/david-gates-lady-valentine.md

  gitlab.com/…/source/…-lady-valentine.md

---
title     : David Gates - Lady Valentine
date      : 2014/03/25 07:35:05
tags      : [jazz, 80s]
category  : [lyric]
---

She's a real look  
cause she's my heart my inspiration  
Lucky is the man who find the child of love

<!-- more -->

[Terminal Dofiles][one-link].

Your the music your my song  
Here with me is where you belong

![Business Card][one-image]

Your the rythm, your my ryhme  
Keep me right into the time  
And I'm so happy when you're here

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

[one-image]:    /site/images/adverts/one-page.png
[one-link]:     https://gitlab.com/epsi-rns/dotfiles/tree/master/terminal/

Content: Bulma Helper

However, there is another way, using hexo’s helper.

• gitlab.com/…/source/…-lady-valentine.md

---
title     : David Gates - Lady Valentine
date      : 2014/03/25 07:35:05
tags      : [jazz, 80s]
category  : [lyric]
---

She's a real look  
cause she's my heart my inspiration  
Lucky is the man who find the child of love

<!-- more -->

{% link Terminal Dofiles "https://gitlab.com/epsi-rns/dotfiles/tree/master/terminal/" %}.

Your the music your my song  
Here with me is where you belong

Your the rythm, your my ryhme  
Keep me right into the time  
And I'm so happy when you're here

-- -- --

### What's next ?

Our next song would be {% post_link lyrics/heatwave-all-i-am %}.

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.

$ tree source/site source/posts
source/site
└── images
    ├── adverts
    │   └── one-page.png
    ├── authors
    │   └── epsi-vexel.png
    └── license
        ├── cc-0.png
        ├── cc-by-nc-nd.png
        ├── cc-by-nc.png
        ├── cc-by-nc-sa.png
        ├── cc-by-nd.png
        ├── cc-by-sa.png
        └── cc-pdm.png
source/posts
└── 2018
    ├── kiddo-007.jpg
    └── kiddo-008-s.jpg

5: Hexo Admin

There are though, a markdown editor. Not as fancy as ViM. But this is useful to test markdown.

• github.com/jaredly/hexo-admin

It is also very easy to setup. All you need to know is already, in the README.md of that repository. And access it in:

• http://localhost:4000/admin/

View

Here is the list of the posts.

Edit

You can edit one by one.

Setting

And you can also edit the frontmatter.

Now we are done with markdown content. Your content has been served.

Note

This hexo admin is only for local, and does not have any capability to write to git repository.

But still, this is inspiring. And maybe also useful for client, who does not familiar with static site.

What is Next ?

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

Thank you for reading.