[Hexo] - Hexo Quick Guide

What is Hexo?

• Documentation | Hexo

Hexo is a fast, simple and powerful blog framework. You write posts in Markdown (or other markup languages) and Hexo generates static files with a beautiful theme in seconds.

Installation

Prerequisites

• Git
• Node.js
• NPM or YARN

Mac

brew install hexo

Majaro

yay hexo

Windows

yarn global add hexo-cli

Initialization

Once Hexo is installed, run the following commands to initialize Hexo in the target <folder>.

hexo init <folder>
cd <folder>
yarn

Plugins

• amehime/hexo-renderer-multi-markdown-it
• multi-markdown-it 安装与配置

Warning

Make sure you're inside the main hexo directory before starting this guide.

Theme Shoka required plugins

Install hexo-renderer-multi-markdown-it

A default Hexo installation will include a markdown renderer plugin which uses marked, so you will have to remove it if you want to use this renderer.

yarn remove hexo-renderer-marked

If you have already removed the default renderer, and others you might of added, you can now safely install hexo-renderer-multi-markdown-it.

yarn add hexo-renderer-multi-markdown-it

if an error is reported as

ERROR: Failed to download Chromium r515411! Set "PUPPETEER_SKIP_CHROMIUM_DOWNLOAD" env variable to skip download.

please try again with the following command

yarn add hexo-renderer-multi-markdown-it --ignore-scripts

Configuration

Configuring the renderer is a fairly simple task because all the settings are in the main hexo _config.yml file.

You just need to open it in your favourite text editor and write down your configuration.

# opitions for renderer
markdown:
  render:
    html: false
    xhtmlOut: true
    breaks: true
    linkify: true
    typographer:
    quotes: '“”‘’'
  plugins:
    - plugin:
        name: markdown-it-toc-and-anchor
        enable: true
        options:
          tocClassName: 'toc'
          anchorClassName: 'anchor'
    - plugin:
        name: markdown-it-multimd-table
        enable: true
        options:
          multiline: true
          rowspan: true
          headerless: true
    - plugin:
        name: ./markdown-it-furigana
        enable: true
        options:
          fallbackParens: "()"
    - plugin:
        name: ./markdown-it-spoiler
        enable: true
        options:
          title: "你知道得太多了"

# options for minify
minify:
  html:
    enable: true
    exclude:
      - '**/json.ejs'
      - '**/atom.ejs'
      - '**/rss.ejs'
  css:
    enable: true
    exclude:
      - '**/*.min.css'
  js:
    enable: true
    mangle:
      toplevel: true
    output:
    compress:
    exclude:
      - '**/*.min.js'

Install hexo-autoprefixer

yarn add hexo-autoprefixer --save

Configuration

Edit _config.yml

autoprefixer:
  exclude:
    - '*.min.css'

Install hexo-algoliasearch

title: Danger
If you leave algolia required settings blank, your website will be stuck on loading. You can skip this step if search reature is not necessary for you.

yarn add hexo-algoliasearch --save

Configuration

Edit _config.yml

algolia:
  appId: #Your appId
  apiKey: #Your apiKey
  adminApiKey: #Your adminApiKey
  chunkSize: 5000
  indexName: #"shoka"
  fields:
    - title #必须配置
    - path #必须配置
    - categories #推荐配置
    - content:strip:truncate,0,2000
    - gallery
    - photos
    - tags

Install hexo-symbols-count-time

yarn add hexo-symbols-count-time

Install hexo-feed

yarn add hexo-feed --save-dev

Configuration

Edit _config.yml

feed:
    limit: 20
    order_by: "-date"
    tag_dir: false
    category_dir: false
    rss:
        enable: true
        template: "themes/shoka/layout/_alternate/rss.ejs"
        output: "rss.xml"
    atom:
        enable: true
        template: "themes/shoka/layout/_alternate/atom.ejs"
        output: "atom.xml"
    jsonFeed:
        enable: true
        template: "themes/shoka/layout/_alternate/json.ejs"
        output: "feed.json"

Other required pluins

Install hexo-hide-posts

• 在 Hexo 中隐藏文章

yarn add hexo-hide-posts

Configuration

1. Edit _config.yml

# hexo-hide-posts
hide_posts:
  enable: true
  # Change the filter name to fit your need
  filter: hidden
  # Generators which you want to expose all posts (include hidden ones) to.
  # Common generators: index, tag, category, archive, sitemap, feed, etc.
  public_generators: []
  # Add "noindex" meta tag to prevent hidden posts from being indexed by search engines
  noindex: true

2. Edit Front-matter

hidden: true

Install hexo-abbrlink

• hexo-abbrlink
• Hexo 生成永久文章链接 - 知乎

yarn add hexo-abbrlink --save

Configuration

Edit _config.yml

permalink: posts/:abbrlink/
abbrlink:
  alg: crc32      #support crc16(default) and crc32
  rep: hex        #support dec(default) and hex

Theme - Shoka

Warning

Make sure you're inside the main hexo directory before starting this guide.

Quick ## Quick install

install

# cd your-blog
git clone https://github.com/amehime/hexo-theme-shoka.git ./themes/shoka

Apply theme

theme: shoka

Configuration

1. Create <root>/_config.shoka.yml
2. Edit _config.shoka.yml according to Step.2 基本配置

Deployment - Github Pages

Warning

Make sure you're inside the main hexo directory before starting this guide.

• 利用(微软)Azure DevOps 实现 Hexo 自动部署
• 2022【保姆级教程】含泪搭建 hexo 博客

Install hexo-deployer-git

yarn add hexo-deployer-git --save

Configuration

Edit _config.yml (with example values shown below as comments):

deploy:
  type: git
  repo: <repository url> # https://bitbucket.org/JohnSmith/johnsmith.bitbucket.io
  branch: [branch]
  message: [message]

Option	Description	Defaut
repo	URL of the target repository
branch	Branch name.	gh-pages (Github) coding-pages (Coding.net) master (others)
message	Customize commit message.	Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}
token	Optional token value to authenticate with the repo. Prefix with $ to read token from environment variable

Warning

While this plugin can parse authentication token from the config, only use this method if you are sure the config will not be committed, including to a private repo. A more secure approach is to add it to the CI as an environment variable, then simply add the name of the environment variable to this plugin's config (e.g. $GITHUB_TOKEN).

title: Danger
Type PAT in `token` does not work now!

Import public key and private key

Warning

Make sure your public/private keys are already generated before starting this guide.

Instead of PAT, hexo-deployer-git works greate with public/private keys.

Imort public key to Github

Import private key to Azure DevOps

1. Create a repository on Github.
2. Create a Azure DevOps Pipeline with CI variables.

# Starter pipeline
# Start with a minimal pipeline that you can customize to build and deploy your code.
# Add steps that build, run tests, deploy, and more:
# https://aka.ms/yaml

trigger:
- main

pool:
  vmImage: ubuntu-latest	# hexo-cli does not work on Windows.

steps:
- script: |
    git config --global user.email "$(EMAIL)"
    git config --global user.name "$(USERNAME)"
    git clone https://github.com/amehime/hexo-theme-shoka.git ./themes/shoka
    npm install -g hexo-cli
    npm install hexo-deployer-git --save
  displayName: 'Installing dependencies...'

# (Option) Sync Azure DevOps repo to Github Repo.
- task: mirror-git-repository-vsts-task@1
  inputs:
    sourceGitRepositoryUri: '$(Build.Repository.Uri)'
    destinationGitRepositoryUri: '$(HEXO_SOURCE_REPO)'
    destinationGitRepositoryPersonalAccessToken: '$(PERSONAL_ACCESS_TOKEN)'

- task: InstallSSHKey@0
  inputs:
    knownHostsEntry: 'github'
    sshKeySecureFile: 'Ed25519'	# Secure file name.

- task: Npm@1
  inputs:
    command: 'install'

- script: |
    ssh-keyscan github.com > ~/.ssh/known_hosts
    hexo clean
    hexo d
  displayName: 'Deploying...'

3. Azure DevOps -> Pipelines -> Library -> Add Secure file

4. Click the secure file, then set pipeline permissions.

Writing

New a post

hexo n "Title"

Enable Katex and Mermaid

Edit front-matter.

math: true
mermaid: true