diff --git a/content/en/hosting-and-deployment/hosting-on-github.md b/content/en/hosting-and-deployment/hosting-on-github.md deleted file mode 100644 index 76de0f3a5..000000000 --- a/content/en/hosting-and-deployment/hosting-on-github.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Host on GitHub -linktitle: Host on GitHub -description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with Github Action Workflow -date: 2014-03-21 -publishdate: 2014-03-21 -categories: [hosting and deployment] -keywords: [github,git,deployment,hosting] -authors: [Spencer Lyon, Gunnar Morling] -menu: - docs: - parent: "hosting-and-deployment" - weight: 30 -weight: 30 -sections_weight: 30 -toc: true -aliases: [/tutorials/github-pages-blog/] ---- - -GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service] and automating development workflows and build with [GitHub Actions]. - -## Assumptions - -1. You have Git 2.8 or greater [installed on your machine][installgit]. -2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free. -3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start]. - -## Types of GitHub Pages - -There are two types of GitHub Pages: - -- User/Organization Pages (`https://.github.io/`) -- Project Pages (`https://.github.io//`) - -Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use. - -## Branches for GitHub Actions - -The GitHub Actions used in these instructions pull source content from the `main` branch and then commit the generated content to the `gh-pages` branch. This applies regardless of what type of GitHub Pages you are using. This is a clean setup as your Hugo files are stored in one branch and your generated files are published into a separate branch. - -## GitHub User or Organization Pages - -As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: - -1. You must create a repository named `.github.io` or `.github.io` to host your pages -2. By default, content from the `main` branch is used to publish GitHub Pages - rather than the `gh-pages` branch which is the default for project sites. However, the GitHub Actions in these instructions publish to the `gh-pages` branch. Therefore, if you are publishing GitHub pages for a user or organization, you will need to change the publishing branch to `gh-pages`. See the instructions later in this document. - -## Build Hugo With GitHub Action - -GitHub executes your software development workflows. Every time you push your code on the GitHub repository, GitHub Actions will build the site automatically. - -Create a file in `.github/workflows/gh-pages.yml` containing the following content (based on [actions-hugo](https://github.com/marketplace/actions/hugo-setup)): - -```yml -name: github pages - -on: - push: - branches: - - main # Set a branch that will trigger a deployment - pull_request: - -jobs: - deploy: - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v3 - with: - submodules: true # Fetch Hugo themes (true OR recursive) - fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod - - - name: Setup Hugo - uses: peaceiris/actions-hugo@v2 - with: - hugo-version: 'latest' - # extended: true - - - name: Build - run: hugo --minify - - - name: Deploy - uses: peaceiris/actions-gh-pages@v3 - if: github.ref == 'refs/heads/main' - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./public -``` - -For more advanced settings [actions-hugo](https://github.com/marketplace/actions/hugo-setup) and [actions-gh-pages](https://github.com/marketplace/actions/github-pages-action). - -## GitHub pages setting - -By default, the GitHub action pushes the generated content to the `gh-pages` branch. This means GitHub has to serve your `gh-pages` branch as a GitHub Pages branch. You can change this setting by going to Settings > GitHub Pages, and change the source branch to `gh-pages`. - -## Change baseURL in config.toml - -Don't forget to rename your `baseURL` in `config.toml` with the value `https://.github.io` for your user repository or `https://.github.io/` for a project repository. - -Unless this is present in your `config.toml`, your website won't work. - -## Use a Custom Domain - -If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirement of GitHub Pages. - -Refer to the [official documentation for custom domains][domains] for further information. - -[config]: /getting-started/configuration/ -[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ -[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages -[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ -[ghsignup]: https://github.com/join -[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/ -[installgit]: https://git-scm.com/downloads -[orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checkout.txt---orphanltnewbranchgt -[Quick Start]: /getting-started/quick-start/ -[submodule]: https://github.com/blog/2104-working-with-submodules -[worktree feature]: https://git-scm.com/docs/git-worktree -[GitHub Actions]: https://docs.github.com/en/actions diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-1.png b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-1.png new file mode 100644 index 000000000..29912f25c Binary files /dev/null and b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-1.png differ diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-2.png b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-2.png new file mode 100644 index 000000000..0050d33e2 Binary files /dev/null and b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-2.png differ diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-3.png b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-3.png new file mode 100644 index 000000000..d2904cae1 Binary files /dev/null and b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-3.png differ diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-4.png b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-4.png new file mode 100644 index 000000000..75774462b Binary files /dev/null and b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-4.png differ diff --git a/content/en/hosting-and-deployment/hosting-on-github/gh-pages-5.png b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-5.png new file mode 100644 index 000000000..efe26129a Binary files /dev/null and b/content/en/hosting-and-deployment/hosting-on-github/gh-pages-5.png differ diff --git a/content/en/hosting-and-deployment/hosting-on-github/index.md b/content/en/hosting-and-deployment/hosting-on-github/index.md new file mode 100644 index 000000000..7123c9d2d --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-github/index.md @@ -0,0 +1,180 @@ +--- +title: Host on GitHub +linktitle: Host on GitHub +description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with Github Actions +categories: [hosting and deployment] +keywords: [github,git,deployment,hosting] +menu: + docs: + parent: "hosting-and-deployment" + weight: 30 +weight: 30 +toc: true +aliases: [/tutorials/github-pages-blog/] +--- + +GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its GitHub Pages service and automating development workflows and build with GitHub Actions. + +## Prerequisites + +1. [Create a GitHub account] +2. [Install Git] +3. [Create a Hugo site] and test it locally with `hugo server`. + +[Create a GitHub account]: https://github.com/signup +[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Create a Hugo site]: http://localhost:1313/getting-started/quick-start/ + +## Types of sites + +There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com. + +{{% note %}} +See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. + +[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites +{{% /note %}} + + +[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites + +## Procedure + +Step 1 +: Create a GitHub repository. + +Step 2 +: Push your local repository to GitHub. + +Step 3 +: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In then center of your screen you will see this: + +![screen capture](gh-pages-1.png) +{style="max-width: 280px"} + +Step 4 +: Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. + +![screen capture](gh-pages-2.png) +{style="max-width: 280px"} + +Step 5 +: Create an empty file in your local repository. + +```text +.github/workflows/hugo.yaml +``` + +Step 6 +: Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed. + +{{< code file=".github/workflows/hugo.yaml" >}} +# 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 one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +# Default to bash +defaults: + run: + shell: bash + +jobs: + # Build job + build: + runs-on: ubuntu-latest + env: + HUGO_VERSION: 0.111.2 + steps: + - name: Install Hugo CLI + 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: Install Dart Sass Embedded + run: sudo snap install dart-sass-embedded + - name: Checkout + uses: actions/checkout@v3 + with: + submodules: recursive + fetch-depth: 0 + - name: Setup Pages + id: pages + uses: actions/configure-pages@v3 + - name: Install Node.js dependencies + run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true" + - 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@v1 + 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@v1 +{{< /code >}} + +Step 7 +: Commit the change to your local repository with a commit message of something like "Add workflow", and push to GitHub. + +Step 8 +: From GitHub's main menu, choose **Actions**. You will see something like this: + +![screen capture](gh-pages-3.png) +{style="max-width: 350px"} + +Step 9 +: When GitHub has finished building and deploying your site, the color of the status indicator will change to green. + +![screen capture](gh-pages-4.png) +{style="max-width: 350px"} + +Step 10 +: Click on the commit message as shown above. You will see this: + +![screen capture](gh-pages-5.png) +{style="max-width: 611px"} + +Under the deploy step, you will see a link to your live site. + +In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes. + +## Additional resources + +- [Learn more about GitHub Actions](https://docs.github.com/en/actions) +- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) +- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)