Skip to content

Commit

Permalink
Update GH docs to say "main" as default branch
Browse files Browse the repository at this point in the history
  • Loading branch information
@maco @bep
maco authored and bep committed Nov 6, 2020
1 parent 4f20bf2 commit 943f3c9
Showing 1 changed file with 16 additions and 16 deletions.
32 changes: 16 additions & 16 deletions docs/content/en/hosting-and-deployment/hosting-on-github.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ To create a Project Pages site, choose a method from the *Project Pages* section
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 use a `<USERNAME>.github.io` to host your **generated** content
2. Content from the `master` branch will be used to publish your GitHub Pages site
2. Content from the `main` branch will be used to publish your GitHub Pages site

This is a much simpler setup as your Hugo files and generated content are published into two different repositories.

Expand All @@ -58,7 +58,7 @@ This is a much simpler setup as your Hugo files and generated content are publis
5. Once you are happy with the results:
* Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
* Before proceeding run `rm -rf public` to completely remove the `public` directory
6. `git submodule add -b master https://github.com/<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository).
6. `git submodule add -b main https://github.com/<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository).
7. Make sure the `baseURL` in your config file is updated with: `<USERNAME>.github.io`

### Put it Into a Script
Expand Down Expand Up @@ -92,7 +92,7 @@ fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
git push origin main
```


Expand All @@ -106,9 +106,9 @@ That's it! Your personal page should be up and running at `https://<USERNAME>.gi
Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `<USERNAME>.github.io/<PROJECT>/`) and not a custom domain.
{{% /note %}}

### Deployment of Project Pages from `/docs` folder on `master` branch
### Deployment of Project Pages from `/docs` folder on `main` branch

[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your main branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:

```
publishDir = "docs"
Expand All @@ -117,18 +117,18 @@ publishDir = "docs"
publishDir: docs
```

After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
After running `hugo`, push your main branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:

1. Go to **Settings** &rarr; **GitHub Pages**
2. From **Source**, select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
2. From **Source**, select "main branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.

{{% note %}}
The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control.
The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on main, and not everyone prefers the output site live concomitantly with source files in version control.
{{% /note %}}

### Deployment of Project Pages From Your `gh-pages` branch

You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
You can also tell GitHub pages to treat your `main` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:

* It keeps your source and generated website in different branches and therefore maintains version control history for both.
* Unlike the preceding `docs/` option, it uses the default `public` folder.
Expand All @@ -139,7 +139,7 @@ These steps only need to be done once. Replace `upstream` with the name of your

##### Add the `public` Folder

First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the main branch:

```
echo "public" >> .gitignore
Expand All @@ -154,7 +154,7 @@ git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push upstream gh-pages
git checkout master
git checkout main
```

#### Build and Deployment
Expand Down Expand Up @@ -225,14 +225,14 @@ cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)

This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing.

### Deployment of Project Pages from Your `master` Branch
### Deployment of Project Pages from Your `main` Branch

To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
To use `main` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.

You will also need to set `master` as your publishable branch from within the GitHub UI:
You will also need to set `main` as your publishable branch from within the GitHub UI:

1. Go to **Settings** &rarr; **GitHub Pages**
2. From **Source**, select "master branch" and then **Save**.
2. From **Source**, select "main branch" and then **Save**.

## Use a Custom Domain

Expand All @@ -243,7 +243,7 @@ Refer to the [official documentation for custom domains][domains] for further in
[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/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch
[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
Expand Down

0 comments on commit 943f3c9

Please sign in to comment.