In this post, I will be running you through all of the directories in Hexo as well as instructions with how to write articles, edit posts and the layout, customize themes, install plugins, and more.
To begin, I will try to differentiate the difference between the files on your local machine and those that are on GitHub Pages.
These are the files that I would recommend adding to your preferred version control system, such as GitHub. Hexo by default will provide a
.gitignore file to ignore Hexo logs and other basic assets. Remember to create a separate repository for the files locally, NOT the repository for your GitHub Page.
So what exactly is on your GitHub Pages repository? Those are the HTML, CSS, and JS files generated by Hexo to build the static website. These are built when you call
hexo generate and are stored in a folder called
public which is then pushed to your GitHub Pages directory.
At the root of the directory (the folder where you set up your website), you should see the following files and directories
This file is that stores various data like posts, tags, etc. when you are running your website locally with the command
All of the node modules (think “node plugins”) that are installed are held in this directory. If you ever happen to delete it, simply run
npm install again to restore them.
These are the plugins and modules that we need in order to run Hexo. It is managed by
npm and the are installed by running
npm install which we had already done in the previous tutorial
Once Hexo builds your website, it stores all of the HTML, CSS, and image assets in this folder which is pushed to your GitHub pages directory and published for the world to see.
This folder contains your layouts and templates for basic post types, such as
draft which we will cover down below.
This is probably the most important folder. All of your posts, images, and various files will all be located here. Hexo will look through the files under
_posts and build pages in HTML out of them, which reference
images and other files in the directory.
Folder to hold all of the themes that you have installed.
Rather than re-writing this from scratch, Hexo already has an incredible tutorial. I will simply be copy-pasting their article in this section.
If you aren’t familiar with markdown, check out this incredible markdown cheatsheet.
To create a new post or a new page, you can run the following command:
post is the default
layout, but you can supply your own. You can change the default layout by editing the
default_layout setting in
There are three default layouts in Hexo:
draft. Files created by each of them is saved to a different path. Newly created posts are saved to the
If you don’t want your posts processed, you can set
layout: false in front-matter.
By default, Hexo uses the post title as its filename. You can edit the
new_post_name setting in
_config.yml to change the default filename. For example,
:year-:month-:day-:title.md will prefix filenames with the post creation date. You can use the following placeholders:
||Post title (lower case, with spaces replaced by hyphens)|
||Created year, e.g.
||Created month (leading zeros), e.g.
||Created month (no leading zeros), e.g.
||Created day (leading zeros), e.g.
||Created day (no leading zeros), e.g.
Previously, we mentioned a special layout in Hexo:
draft. Posts initialized with this layout are saved to the
source/_drafts folder. You can use the
publish command to move drafts to the
publish works in a similar way to the
Drafts are not displayed by default. You can add the
--draft option when running Hexo or enable the
render_drafts setting in
_config.yml to render drafts.
When creating posts, Hexo will build files based on the corresponding file in
scaffolds folder. For example:
When you run this command, Hexo will try to find
photo.md in the
scaffolds folder and build the post based on it. The following placeholders are available in scaffolds:
||File created date|
Installing a theme is relatively easy in Hexo. Simply choose one that you like from a diverse library, download it, and place the folder in your
Next, you want to change the
theme: tag under
For example, I’m using
hexo-theme-next so the tag for me would be:
Furthermore, my theme directory looks like the following (I have multiple themes installed):
Once again, there’s no need for me to re-write wonderful documentation that already exists, so I will be taking from Hexo again.
If you’re working from a theme, make sure to edit in
Templates define the presentation of your website by describing what each page should look like. The table below shows the corresponding template for every available page. At the very least, a theme should contain an
When pages share a similar structure - for instance, when two templates have both a header and a footer - you can consider using a
layout to declare these structural similarities. Every layout file should contain a
body variable to display the contents of the template in question. For example:
By default, the
layout template is used by all other templates. You can specify additional layouts in the front-matter or set it to
false to disable it. It’s even possible to build a complex nested structure by including more layout templates in your top layout.
Partials are useful for sharing components between your templates. Typical examples include headers, footers or sidebars. You may want to put your partials in separate files to make maintaining your website significantly more convenient. For example:
You can define local variables in templates and use them in other templates.
If your theme is exceedingly complex or if the number of files to generate becomes too large, Hexo’s file generation performance may begin to decrease considerably. Aside from simplifying your theme, you may also try Fragment Caching, which was introduced in Hexo 2.7.
This feature was borrowed from Ruby on Rails. It causes content to be saved as fragments and cached for when additional requests are made. This can reduce the number of database queries and can also speed up file generation.
Fragment caching is best used for headers, footers, sidebars or other static content that is unlikely to change from template to template. For example:
Though it may be easier to use partials:
Don’t use fragment caching when the
relative_link setting has been enabled. This may cause issues because relative links can and probably will be different depending on the pages they appear in.
This part of the tutorial will not be covering how to develop and share your own plugins. This has already been documented by Hexo.
Look for a plugin that you want to install, whether its from the official listing or elsewhere on the internet, and run
npm install --save plugin-name. The
--save tag adds the plugin to
packages.json so that next time you call
npm install, the plugin will automatically be installed.
Each plugin will also have additional parameters which need to be set up. You can add this in the
_config.yml file such as:
After making changes, you can run
hexo server to test out the changes locally before deploying to live with the following sequences:
This article should have covered everything that you would need to get your website up and going! If there are any other features that you’re confused about and would like me to cover, please leave a comment in Disqus below!