Update GitHub hosting instructions (#1991)

Closes #1990

content/en/hosting-and-deployment/hosting-on-github.md

@@ -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://<USERNAME|ORGANIZATION>.github.io/`)
-- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`)
-
-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 `<USERNAME>.github.io` or `<ORGANIZATION>.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://<USERNAME>.github.io` for your user repository or `https://<USERNAME>.github.io/<REPOSITORY_NAME>` 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

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)