Intro
This is part one of a mini series on my journey to build my own blogging site without using WordPress or any blogging site like Tumbler or Medium. I want full control of my published thoughts. This includes if (or how) I should share my data with advertisers and crawlers.
I assume you are comfortable with using git, VScode, and markdown. There are other sites that discuss how to get started with GitHub and programming.
Getting Started in VScode
Arguably one of the best (and free) coding editors is Microsoft’s Visual Studio Code. It has a huge marketplace for extensions (or plugins) to handle any popular framework and programming language.
Download & install vscode:
Install extensions
These are the extensions I use to create blog posts and update my blog’s theme.
Be sure that VScode has the install path defined for the command line.
Customize your VScode environment
I typically setup the editor with my favorite color theme and set the wrap length (based on my screen width) plus font sizes. You’ll want it comfortable to your eyes.
What is 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.
This entire site is built on the Hexo framework with a heavily customized theme of my own design. The reason I selected Hexo is that it’s built on NodeJS. Having both the frontend and backends written in JavaScript makes management of the website far easier. Plus, JavaScript remains a very popular scripting language with easy to find affordable help to enhance it further. I recall the pain of managing several programming languages for a single project. This blog only requires CSS, HTML, and JavaScript. Even the backend on AWS is simple JavaScript.
I’ve spent the past 18 months digging into the framework and making a few minor contributions to the project. I’m now very comfortable with how it works and how to enhance it with custom tags and scripting.
Hexo Tutorial
setup HEXO environment
After you download the Hexo package to your project folder, you’ll need to overwrite some files as I define below.
config
Need to setup the global config for HEXO and the FrontMatter CMS in VScode.
The global config needs to be updated to use my custom theme. Here’s what I use for version 2022.04:
1 |
|
Be sure to update the blog domain to your site.
Need to ensure the correct npm packages are installed
1 |
|
After copying this file to the root of the project, run npm install
to download all the dependencies.
scaffolds
Scaffolds are essentially template files with default values defined in the front-matter section of the markdown file. When you specify hexo new draft ...
on the command line, you are telling Hexo to use the draft.md
file in the /scaffolds/
folder. My theme has some expected values and I define them well in the scaffolds. You’ll need to copy these files to your project folder.
1 |
|
1 |
|
basic commands
As your blog grows in size, you’ll notice that it starts to take longer to build the site. This is because Hexo is comparing the posts with the db.json
file it builds each run. I found it much faster to force a clean run by adding hexo clean
to the command before building or testing.
When I’m testing the site locally, I simply run:
hexo clean && hexo server
After confirming that everything looks as expected, I’ll build the site:
hexo clean && hexo gc -w=100 && hexo gen
This will clear the database file, extract the calendar data for 100 weeks, and generate the site.
Node heap memory
As more advanced features are added to the theme, the amount of memory required to process it will increase. Here’s the command to increase Node’s memory allocation.
1 |
|
This will increase the memory buffer to 8GB. For my project with over 1400 posts, I needed to increase it to 14GB before it would compile completely. Needless to say, your hardware will need to accommodate these requirements.
FrontMatter
Setup FrontMatter plugin:
As of FrontMatter version 8.1.2, it doesn’t support Hexo out-of-the-box, but it does a great job of providing a headless CMS. I requested the creator to add support - frontMatter.framework.id: “HEXO”. Hopefully, you are reading this after a newer version is published.
In the root of your project you’ll need to overwrite this configuration file.
🧑🏻💻 frontmatter.json
1 |
|
Once you’ve updated FrontMatter’s configuration, you can click on the FM tab in VScode to see the panel now supports HEXO with my custom theme.
Setup GitHub
This repo uses LFS
Run the following command to enable proper authentication with GitHub LFS servers:
1 |
|
Update Git Buffers
It appears that the default git buffer is too small for sites with large posts or video files. Need to set it to the max:
1 |
|
Git buffer requirements will depend on the amount of RAM available to your machine.
Support long filenames
This issue affects mostly Windows users. You may need to run this as Administrator
for it to be effective.
1 |
|
Basic blog workflow
- Find topic for discussion. I often see an image of something that sparks an idea to discuss. As I do everything on my MacBookPro, MacOS has case sensitive filenames. So, I try to be mindful of this when creating the blog title. If I start the title in all lowercase, then the filename will be lowercase too. From the command line, create a new draft:
hexo new draft "My new idea or thought"
- View the basic preview within VScode until I’m ready to preview it with the theme. FrontMatter can run the HEXO server for you and display the preview live within VScode.
- When I’m satisfied with the article, I’ll update the draft and publish status in FrontMatter panel. I’ll also review all the options for the article to ensure I have the best keywords, tags, related posts, description, etc.
- Build the site and make sure no errors are found.
- Commit the updates to git and push to my repo.
- Assuming my Ci/Cd automation is working, then I should see the page on my live website within 10 minutes.
Reference
- Running Visual Studio Code on macOS
- How can you export the Visual Studio Code extension list?
- How to export your VS Code extensions from terminal
- How to use Github and Vercel to Deploy a Hexo Blog and Config it
- https://support.snyk.io/hc/en-us/articles/360002046418-JavaScript-heap-out-of-memory
- https://stackoverflow.com/questions/22575662/filename-too-long-in-git-for-windows