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
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.
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:
-
Frontmatter: YAML, or JSON
-
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).
-
Frontmatter: YAML or JSON
-
Content: Markdown
-
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.
---
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.
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:
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.