Prerequisites

The following tools must be installed on your system before proceeding:

• Git
• Node.js (and npm)

Configuring GitHub

Setting Up SSH Authentication

SSH keys provide a secure method for authenticating with GitHub without using passwords.

Generating an SSH Key Pair: Open a terminal and run the following command, substituting your GitHub email address:

ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

Press Enter to accept the default file location and to create a passphrase (or leave it empty).

The public key is stored in ~/.ssh/id_rsa.pub. Open this file with a text editor and copy its entire contents.

Adding the Public Key to GitHub:

1. Log into your GitHub account and navigate to Settings.
2. In the left sidebar, select SSH and GPG keys.
3. Click New SSH key.
4. Provide a descriptive title (e.g., "My Laptop") and paste the copied public key into the "Key" field.
5. Click Add SSH key.

Creating a GitHub Pages Repository

1. On GitHub, click the + icon in the top-right corner and select New repository.
2. Name the repository yourusername.github.io, where yourusername is your exact GitHub username.
3. Initialize the repository (you can add a README later).
4. After creation, go to the repository's Settings, then navigate to the Pages section. Select the main branch as the source and save. Your site will be published at https://yourusername.github.io.

Setting Up Hexo Locally

Hexo is a static site generator that transforms Markdown files into a complete website.

Installation and Initialization

Navigate to your preferred project directory in the terminal and execute the following commands:

# Install the Hexo command-line tool globally
npm install -g hexo-cli

# Initialize a new Hexo site in the current directory
hexo init my-blog
cd my-blog

# Install required dependencies
npm install

Running the Local Server

Generate the static files and start the local development server:

hexo generate  # or `hexo g`
hexo server    # or `hexo s`

Visit http://localhost:4000 in your browser. The default Hexo welcome page should appear, confirming a successful local setup.

If port 4000 is occupied, specify an alternative port:

hexo server -p 5000

Project Structure Overview

Key directories and files in a Hexo project:

• _config.yml: The primary configuration file for the site.
• scaffolds/: Contains templates for new posts and pages.
• source/: Stores user content.
  • _posts/: Directory for all blog posts (.md files).
• themes/: Contains installed themes.
• public/: The generated static HTML files (created after running hexo generate).

Deploying to GitHub Pages

To publish your local Hexo site to your GitHub Pages repository, you need a deployment plugin.

1. Install the hexo-deployer-git plugin:

   npm install hexo-deployer-git --save
   

2. Edit the _config.yml file in your project's root directory. Locate the deploy section and configure it with your repository's SSH URL and target branch:

   deploy:
     type: git
     repo: git@github.com:yourusername/yourusername.github.io.git
     branch: main
   

3. Deploy your site:

   hexo clean    # Cleans the public directory and cache
   hexo generate # Generates static files
   hexo deploy   # or `hexo d` - Pushes files to the GitHub repository
   

After a few moments, your blog will be live at https://yourusername.github.io.

Connecting a Custom Domain

You can replace the github.io subdomain with a custom domain name.

1. Acquire a Domain

Purchase a domain from a registrar like Namecheap, Google Domains, or Namesilo.

2. Configure DNS Records

In your domain registrar's DNS management panel, add the following records:

Type	Host / Name	Value / Points To	TTL
A	@	185.199.108.153	3600
A	@	185.199.109.153	3600
A	@	185.199.110.153	3600
A	@	185.199.111.153	3600
CNAME	www	yourusername.github.io.	3600

Note: The IP addresses above are GitHub's Pages server IPs. The trailing dot in the CNAME value is important.

3. Configure GitHub Pages

1. In your GitHub repository (yourusername.github.io), go to Settings > Pages.
2. Under Custom domain, enter your custom domain (e.g., example.com) and click Save.
3. Optionally, select the Enforce HTTPS checkbox once it becomes available (it may take time to activate).

DNS changes can take up to 48 hours to propagate globally, though it often happens much faster.

Essential Hexo Commands

# Create a new blog post
hexo new "Post Title"

# Generate static files
hexo generate  # Short: hexo g

# Start the local preview server
hexo server    # Short: hexo s

# Clean generated files and cache
hexo clean

# Deploy to the configured repository
hexo deploy    # Short: hexo d

# A common workflow sequence
hexo clean && hexo g && hexo d

Customizing Appearance with Themes

Hexo supports themes to change the look and feel of your blog. Popular themes include Next, Butterfly, and Icarus.

1. Find a theme in the Hexo Themes directory.
2. Clone the theme into your themes/ directory:

   git clone https://github.com/theme-author/theme-name.git themes/theme-name
   

3. Modify the theme setting in your _config.yml file to the theme's folder name:

   theme: theme-name
   

4. Regenerate and preview your site locally (hexo clean && hexo g && hexo s). Theme configuration options are typically found in the theme's own _config.yml file within the theme folder.