NøTeS blog project

About

This Hexo static site generator has been versioned on Gitlab with a git submodule based on Hexo-Hueman theme.

This topic deals with :

• a local machine where your project will be created and maintained.
• a remote production web-server with Git installed.

Requirements

• Install on your local machine :
  • Node.js + Yarn + Git.
  • Hexo CLI : npm install -g hexo-cli.
• Install Git on your production server .

Setup

We have to maintain two repositories for this project : theme (A) and Hexo one (B).

A. Custom theme project based on Hueman

We choose to keep our custom theme updated from original Hexo-Hueman project originally hosted in Github.

Create your theme project

Create an empty theme project on Gitlab, then locally :

mkdir your-theme-project
cd your-theme-project
git remote add upstream https://github.com/ppoffice/hexo-theme-hueman.git
git pull upstream master
git push origin master

Configuration

This theme requires 2 peer dependencies hexo-pwa and hexo-multiauthor that will NOT be added to parent project package.json file because of conflicts.

1. Rename _config.yml.example to _config.yml.
2. Add your logo in sources/css/images/ and configure your theme.
3. Commit and push changes.

B. Main Hexo project

Even if Hexo could be run directly on a web-server and listening for changes, we choose to publish only static files hosted in the public/ folder from a dedicated production branch thanks to Hexo Git deployer plugin.

Create your blog project

Create an empty blog project on Gitlab, then locally :

hexo init your-project
cd your-project/
git init
git remote add origin https://gitlab.com/your-project.git
npm install hexo-deployer-git --save
git add .
git commit -m "Hexo initial commit"
git push -u origin master
cd themes/
git submodule add https://gitlab.com/your-theme-project.git your-theme-project
cd ..
cd add .
git commit -m "Add submodule your-theme-project"
git push -u origin master

Configuration

Update your _config.yml for deployment :

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  type: git
  repo: https://gitlab.com/your-project.git
  branch: production

Commit your changes and push to origin master, then run hexo clean && hexo deploy.

At this point, a new branch called production is created or updated on your Gitlab repository.
Those two commands only affect this remote branch so master one is not concerned about it.
You still have to publish commits on your master branch to keep your working project up to date.

Workflow

Once first time

1. Clone locally your main project from Gitlab including his submodule:
   git clone --recursive https://gitlab.com/your-project.git.
2. Install dependencies yarn install.
3. Connect to your web-server by SSH and clone your Gitlab production branch:
   git clone --single-branch -b production https://gitlab.com/your-project.git.

Working on your project

1. Start your local server and render drafts: hexo server --draft.
2. Add your posts, drafts, pages … with Hexo CLI.
3. Commit changes and push.
4. Generate and push into production branch your static files that lives into public/ folder:
   hexo clean && hexo deploy.
5. Connect to your web-server by SSH and pull changes.