Hexo is a static site generator that converts Markdown syntax into prebuilt dynamic themes. Hexo’s use of Node.js, HTML, and CSS / YAML makes for a simple, scalable website that is easy to maintain, build upon, or migrate.
Installing Hexo is done with npm, and requires Node.js. To meet these requirements, we first need to install both of these tools. Luckily, there are scripts and commands to help us do so.
# Install NVM to prep for Node
Now that we have everything we need, all that’s left to do is install Hexo -
# Install Hexo with NPM
Creating a site with Hexo requires that we first have an empty directory that we want to build our site within. Create this directory, then run
hexo init to generate the files we will use to build our site.
Our site is generated within
/site/, and within it we can find new files and folders Hexo generated when we ran the
hexo init command on the directory. The basic structure of a hexo blog can be seen below -
_config.yml file contains all of the settings for our site, and its important to step through them carefully to make the changes that may need to be made in order for the site to work properly.
source directory contains all of our drafts, posts, and pages. This blog has no additional pages, so none are seen here, but they would be represented as additional directories within the
source directory, titled with the page name. These page directories contain only the index.md file that is the content.
scaffolds are the defaults used when generating a draft, post, or page using Hexo. These are useful to edit when attempting to configure your changes to initialize with some settings or information, which speeds up the process of adding new content.
public directory is generated by Hexo, and we don’t need to worry much about it.
So, if we wanted to migrate our site from Hexo, the only files we’d need to worry about keeping are the Markdown files within
source. Markdown is widely used across many tools and applications, so finding a new way to use these posts and pages is likely and easy to manage.
Hexo uses prebuilt themes for generating Markdown into webpages. I chose Cactus Dark for this site, and made changes where I seen fit.
Themes are installed by simply navigating to the root directory of your site, and cloning the repository into the
themes directory. See the commands below for an example of installing this theme to a new Hexo site (without any modifications you may see here).
Now within your root directory, modify the
_config.yml to point to the cactus theme we just added. The default theme and value within the
_config.yml is landscape, that value points to the theme directory we cloned above.
After you’ve made pointed your site configuration file to your new theme, run
hexo generate to apply your new theme to your site.
Its important to note that changes to the theme will need to take place within the
/site/theme/cactus/ directory, which may contain a large set of files that are at first unfamilliar to you. After some time poking around your own small site, spend some time looking through the directories and files within your themes directories. They will often provide good examples to use on your own.
Now that we have a site, theme, and files have been configured to our liking, all we need is to start the Hexo server and point nginx to the port its running on. Run
hexo serve & and make the needed changes to your
/etc/nginx/nginx.conf to route the traffic.
Some snippets, guides, or references that may be useful when using Hexo -
Also found by running
hexo -h, see the below help text for a list of commands when using Hexo
Usage: hexo <command>
For more help, you can use ‘hexo help [command]’ for the detailed information
or you can check the Hexo Documentation
Below we can see the basic syntax used when writing raw markdown pages.
The examples above were taken from The Official Markdown Guide
Below is a basic
nginx.conf that serves as an example of passing local traffic to the port running Hexo.
# A simple nginx.conf showing how to pass traffic to a docker container