My Instructions for Using Hexo

Posted on Edited on In Word count in article: 1.1k Reading time ≈ 4 mins.

How to setup HEXO website [my own instructions] [this site]

Just the quick helpdesk for the things I went through to get Hexo working.

Hexo is the static site generator, which is very easy to use and has a lot of plugins and themes. It simplifies creation of website and does not require much programming skills. Hexco site can be published online to access by everyone, with the help of for example GitHub Pages.

Installing Hexo

Instructions to install and setup hexo locally.

Install required packages and than Hexo:

1
2
3
4
# 1. install git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
# 2. install node.js: https://nodejs.org/en/download
# 3. install hexo:
npm install -g hexo-cli

Start first project - first site

Enter folder where you want to create your project and than:

1
2
hex init project_name
cd project_name

start local server

To enjoy whole site locally, before publishing it online:

1
hexo server

create new site/blog post

Creating new content for the site.

1
2
hexo new post_site_name
hexo new "My New Post"

If you desire, the home page of your site may display only some part of the newest article, instead of the whole thing.

To do so put this:

1
<!-- more -->

in the place where ‘Read more’ should appear.

to create draft (not published) post:

1
hexo new draft to_check

to see how draft looks like:

1
hexo server --draft

to publish draft as normal post

1
hexo publish to_check

create a page, not a post

1
hexo new page about_me_page

to enter this site: /about_me_page/

Change default hexo new behaviour

default is post, but can be draft:
in _config.yml:

1
default_layout: post

change to:

1
default_layout: draft

page title, front matter, date, tags

1
2
3
4
5
---
title: Title of the site
date: 2023-03-28 15:07:42
tags: [Tag1, Tag2, Tag3]
---

scaffolds being like templates

can add to them:
author: Me
can add new templates, not only page, post, draft but also my_own by create new my_own.md file inside of the scaffolds folder. Then:

1
hexo new my_own title

it will put it inside of the post folder, or probably a default.

Categories

add inside of the file, at the beginning:

1
2
3
4
categories:
- [Category1]
- [Category2]
- [Category3]

subcategfories, being like index of a book

1
2
3
4
categories:
- [Category1, Category1.1]
- [Category2,Category1.1,Category1.2]
- [Category3]

Plugins

like codebocks

1
2
3
4
5
6
7
8
9
10
{% codeblock %}
some_code = 2*pi();
other = 89;
{% endcodeblock %}

{% codeblock lang:javascript %}
some_code = 2*pi();
other = 89;
{% endcodeblock %}

works like

1
``` in markdown
1
2
some_code = 2*pi();
other = 89;
1
2
some_code = 2*pi();
other = 89;

more plguins:
https://hexo.io/docs/plugins

allow files on site:

in _config.yml:

1
post_asset_folder: false

change to:

1
post_asset_folder: true

Than, creating a new post with hexo new site will aslo crease site folder in addition to site.md in which all media will be located.

To place images use:

1
2
3
4
5
6
7
8
#image
{% asset_img jpgg.jpg %}

#link:
{% asset_link jpgg.jpg %}

#path on server:
{% asset_path yes.png %}
Link preview
/2023/03/28/how_to_use_hexo/jpgg.jpg

custom theme config:

1
hexo server --config _config.next.yml

If updating of the custom theme is planned it is a good manner to create theme configuration file separately from the main one. To do so, create _config.next.yml file in the root folder of the project. In this file the same settings as the one found in the /themes/theme_name/_congig.yml can be used.

Delete post

  1. Delete the post under source/_post folder
  2. Run hexo clean to delete the database (db.json) and assets folder
  3. Run hexo generate to generate the new blog without your deleted post
  4. Run hexo deploy to deploy your blog

in .\site_name\themes\next\layout\_partials\footer.njk
comment:

1
2
3
4
5
6
7
8
9
10
11
{%- if config.symbols_count_time.total_time %}
<span class="post-meta-item">
  <span class="post-meta-item-icon">
    <i class="fa fa-coffee"></i>
  </span>
  {%- if theme.symbols_count_time.item_text_total %}
    <span>{{ __('symbols_count_time.time_total') }} &asymp;</span>
  {%- endif %}
  <span title="{{ __('symbols_count_time.time_total') }}">{{ symbolsTimeTotal(site, config.symbols_count_time.awl, config.symbols_count_time.wpm, __('symbols_count_time.time_minutes')) }}</span>
</span>
{%- endif %}

Deploy Hexo to the interwebs with GitHub Pages

There a re few ways to deploy Hexo site to the internet. One of them is to use GitHub Pages. It is free but will require some setup and site will be published under username.github.io address. That means username of the GitHub account is the same as the site address.

On way is to upload all of the source files to the GitHub repository called username.github.io. Than using GitHub Actions, the site will be automatically generated and published, as described here. During this operation the second branch in the repository will be create where all of the public files will be stored. Another approach is to use upload only public folder to the GitHub repository. This is the way I will describe here.

Firstly,

1
git clone your_site_repository.git

The folder named your site will be created. I set up this GitHub repository folder next to the Hexo site.
In the Hexo site folder, execute 

1
hexo generate

the public folder will be created. Than, content of this folder has to be copied into the username.github.io folder. In Linux cp -u -r public/* ../username.github.io/ will do the job.
Moving to the username.github.io folder, execute:

1
2
3
4
git status 
git add .
git commit -m "Site update"
git push

This will check for the changes in the repository, it will add all the files and commit them
Basic git configuration and authorization is required to upload changes into the repository.

After successful push, using the web interface file .github/workflows/pages.yml should be added. Inside of it the following content shall be pasted:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: Pages
on:
  push:
    branches:
      - main  # default branch
jobs:
  pages:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

It is the same thing located as in here but only contain the last step. In normal deployment described in linked link, the GitHub will generate public/ content based on uploaded source. In here it will only publish uploaded public/ content generated by us locally.

It might be required to go to settings of the webpage repository > Pages on the left side > Build and deployment > Source > Deploy from branch > and pick main branch.

Formatting hints and quick look-ups

Underlined

1
<ins>Underlined</ins>

Bold

Bold vs non-bold

1
**Bold**

Italic

1
***Italic***

Strikethrough

1
~~Strikethrough~~

Quote

Quote

1
> Quote

Code

1
`Code`

New line

<br />

More formatting

<p style="text-align: center; font-size:250%; "><ins>Mgr inż. Aleksander Smolarski</ins></p>

Center image

1
2
3
<div style="text-align: center;">
![alt text](https://markdown.land/wp-content/uploads/2021/06/markdown-512px.png "Our logo")
</div>

or 

1
2
3
4
5
6
7
8
9
10
<img
    style="display: block; 
           margin-left: auto;
           margin-right: auto;
           margin-bottom: 0px;
           margin-top: 0px;
           width: 30%;"
    src="https://markdown.land/wp-content/uploads/2021/06/markdown-512px.png" 
    alt="Our logo">
</img>

Source: https://markdown.land/markdown-center