GitHub pages is possibly the fastest way to serve a [[static website]] for free if you are already using GitHub. 1. In your repo on GitHub, open the **Settings** tab and select **Pages**. 3. In the **Build and deployment** section, under **Source** select "Deploy from a branch". 4. Under **Branch**, select your preferred option (see [[#options]] for details). 5. Click **Save**. GitHub requires a few seconds to create the site, but soon you'll find the link to the site under **Settings > Pages**. This is also where you can unpublish a site.  ### Options There are three ways to create a GitHub pages site. 1. `main` branch: use this option if your entire repo is a static site. 2. `docs/` subfolder on the `main` branch: this is the best option for [[project documentation]]. 3. `gh-pages` branch: this option allows you to create a site entirely from the command line, but be warned you may then need to maintain two branches ( `main` and `gh-pages` ). This is a legacy option and generally not recommended. ### The gh-pages branch You can also create a GitHub Pages site by creating a [[branch]] named `gh-pages` in your repo and push it up to GitHub (setting the upstream while doing so). GitHub will take care of the rest. Again, this is convenient at first but can require more work to manage two branches, so it is not recommended. ```bash git branch gh-pages git push --set-upstream origin gh-pages ``` ### Multiple sites, same repo You can deploy multiple sites from the same repo using GitHub pages. Each site will be at the URL `https://<github-user>.github.io/<repo>/<path/to/dir>`. You can serve multiple [[interactive reports]] in this way. The README in the root will be served as the home page of the repo. To override this behavior, create an `index.html` page in the root of the repo that links to all your reports and other materials. This will create a convenient entry point to the resources on the repo. You can include this in the `gh-pages` branch only if desired. ### Dedicated branch In some instances, you want to include a `gh-pages` branch that includes only the files you want to serve on the site. For instance, the build is failing due to some other content in the repo or the repo is very large. The code below assumes you have a file `index.html` in the root of your repo that you want to act as the main page of your GitHub pages site. ```bash git checkout --orphan gh-pages git reset --hard git checkout main index.html git commit -m "Initializing gh-pages branch" git push origin gh-pages git checkout main ``` An orphan branch is not connected to the other branches and commits and it's working tree has no files at all. This prevents you from accidentally merging the empty `gh-pages` branch with your `main` branch and deleting everything. To update the branch ```bash git checkout gh-pages git checkout main index.html git commit -m "updating gh-pages" git push origin gh-pages git checkout main ``` ### Repo structure Use a well-structured [[project organization for web]], including an `index.html` in the root directory (or subdirectory if serving multiple sites or project documentation). If the site's entry point is not named `index.html`, the URL for the site will need to include the full filename (e.g., `https://...path/to/dir/homePage.html`). > [!example]- Additional Resources > - [Quickstart for GitHub Pages](https://docs.github.com/en/pages/quickstart) > - [MDN Web Docs guide to GitHub Pages](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Using_Github_pages) > - [Deploy on Google App Engine](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/How_do_you_host_your_website_on_Google_App_Engine) instead. > - [Create gh-pages branch in existing repo](https://jiafulow.github.io/blog/2020/07/09/create-gh-pages-branch-in-existing-repo/)