Deploy Site

Hugo generates static websites, allowing for flexible hosting options. This page provides guides for deploying your MaiyiDocs site on various platforms.

Quick Start from Template

 imfing/hextra-starter-template

You could quickly get started by using the above template repository.

We have provided a GitHub Actions workflow which can help automatically build and deploy your site to GitHub Pages, and host it for free. For more options, check out Deploy Site.

🌐 Demo ↗

Start as New Project

There are two main ways to add the MaiyiDocs theme to your Hugo project:

1. Hugo Modules (Recommended): The simplest and recommended method. Hugo modules let you pull in the theme directly from its online source. Theme is downloaded automatically and managed by Hugo.

2. Git Submodule: Alternatively, add MaiyiDocs as a Git Submodule. The theme is downloaded by Git and stored in your project’s themes folder.

Setup MaiyiDocs as Hugo module

Prerequisites

Before starting, you need to have the following software installed:

• Hugo (extended version)
• Git
• Go

Steps

hugo new site my-site --format=yaml

# initialize hugo module
cd my-site
hugo mod init github.com/username/my-site

# add MaiyiDocs theme
hugo mod get github.com/imfing/hextra

module:
  imports:
    - path: github.com/imfing/hextra

hugo new content/_index.md
hugo new content/docs/_index.md

hugo server --buildDrafts --disableFastRender

hugo mod get -u

hugo mod get -u github.com/imfing/hextra

Setup MaiyiDocs as Git submodule

Prerequisites

Before starting, you need to have the following software installed:

• Hugo (extended version)
• Git

Steps

hugo new site my-site --format=yaml

git submodule add https://github.com/imfing/hextra.git themes/hextra

theme: hextra

hugo new content/_index.md
hugo new content/docs/_index.md

hugo server --buildDrafts --disableFastRender

When using CI/CD for Hugo website deployment, it’s essential to ensure that the following command is executed before running the hugo command.

git submodule update --init

Failure to run this command results in the theme folder not being populated with MaiyiDocs theme files, leading to a build failure.

git submodule update --remote

git submodule update --remote themes/hextra

Next

Explore the following sections to start adding more contents:

GitHub Pages

GitHub Pages is the recommended way to deploy and host your website for free.

If you bootstrap the site using hextra-starter-template, it has provided GitHub Actions workflow out-of-the-box that helps automatically deploy to GitHub Pages.

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.147.7
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # fetch all history for .GitInfo and .Lastmod
          submodules: recursive
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Setup Hugo
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

In your repository settings, set the Pages > Build and deployment > Source to GitHub Actions:

By default, the above GitHub Actions workflow .github/workflows/pages.yaml assumes that the site is deploying to https://<USERNAME>.github.io/<REPO>/.

If you are deploying to https://<USERNAME>.github.io/ then modify the --baseURL:

54
55
56
57

run: |
  hugo \
    --gc --minify \
    --baseURL "https://${{ github.repository_owner }}.github.io/"

If you are deploying to your own domain, please change the --baseURL value accordingly.

Cloudflare Pages

1. Put your site source code in a Git repository (e.g. GitHub)
2. Log in to the Cloudflare dashboard and select your account
3. In Account Home, select Workers & Pages > Create application > Pages > Connect to Git
4. Select the repository, and in the Set up builds and deployments section, provide the following information:

For more details, check out:

• Deploy a Hugo site.
• Language support and tools.

Netlify

1. Push your code to your Git repository (GitHub, GitLab, etc.)
2. Import the project to Netlify
3. If you are not using [hextra-starter-template][hextra-starter-template], configure the following manually:
   • Configure the Build command to hugo --gc --minify
   • Specify the Publish directory to public
   • Add Environment variable HUGO_VERSION and set to 0.147.7, or alternatively, set it in netlify.toml file
4. Deploy!

Check Hugo on Netlify for more details.

Vercel

1. Push your code to your Git repository (GitHub, GitLab, etc.)
2. Go to Vercel Dashboard and import your Hugo project
3. Configure the project, select Hugo as Framework Preset
4. Override the Build Command and Install command:
   1. Set Build Command to hugo --gc --minify
   2. Set Install Command to yum install golang