getting-started.md

Quick Start

This guide covers getting started with the blog-build-tools.

Installation

In this Getting Started, you need git, docker and docker-compose.

Git

• Windows: Download & install git.
• Mac: Install it with Homebrew, MacPorts or installer.
• Linux (Ubuntu): sudo apt-get install git-core

Docker

• Windows / Mac
  • https://www.docker.com/products/docker-desktop
• Linux (Ubuntu)
  • docker: https://docs.docker.com/engine/install/ubuntu/
  • docker-compose: https://docs.docker.com/compose/install/

Make sure the following commands are successful:

$ git
$ docker
$ docker-compose

Create a new CSS Blog

Get sample project

Clone jpaztech/blog-build-tools repository and copy example blog directory.

$ git clone https://github.com/jpaztech/blog-build-tools.git
$ cp -r blog-build-tools/example {YOUR_WORKING_DIR}/blog

Initialize Git repository

$ cd {YOUR_WORKING_DIR}/blog
$ git init

Setup blog theme

First, cleanup themes directry.

$ rm -rf themes/*

Add jpazureid/hexo-theme-jpazure blog theme as git submodule

$ git submodule add https://github.com/jpazureid/hexo-theme-jpazure.git themes/jpazure

Customize site configuration file

You can configure most settings here.

$ vim _config.yml

Start / Stop local server

Starts a local server. This is at http://localhost:4000/.

$ docker-compose up
 ...
blog_1  | INFO  Start processing
blog_1  | INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

To stop server, press Ctrl+C and docker-compose down.

^CGracefully stopping... (press Ctrl+C again to force)
Stopping example_blog_1 ... done

$ docker-compose down

Publish Blog with GitHub Pages

In this tutorial, we use GitHub Actions to deploy GitHub Pages.

Commit changes

$ git add .
$ git commit -m 'initial commit'
$ git branch -M main

Push to remote repository

Create a GitHub repository named {ORG_NAME}/blog.

Add new remote and Push commits.

$ git remote add origin https://github.com/${ORG_NAME}/blog.git
$ git push -u origin main

The repository has a workflow definition for GitHub Actions (.github/workflows/pages.yml).

When new changes is pushed to main branch, the workflow triggered. The jobs automatically builds blog page and uploads generated files to gh-pages branch.

You can check workflow runs at Actions section. https://github.com/{ORG_NAME}/blog/actions

Configure GitHub Pages

Once the workflow is finished, the generated pages can be found in the gh-pages branch of the repository.

To publish the page with GitHub Pages, navigate to GitHub Pages section in repository Settings and change Source to gh-pages branch.