Deploy Docusaurus website to GitHub Pages using GitHub Actions
This repository is an example of deploying a Docusaurus website to GitHub Pages using GitHub Actions.
Configuring the GitHub repository
It uses the new GitHub Pages experience with GitHub Actions to deploy the website.
Enable this experience in GitHub.com -> Repository -> Settings -> Pages -> Build and deployment -> Source by selecting GitHub Actions instead of the legacy Deploy from a branch option.
In GitHub.com -> Repository -> Settings -> Environments you should see a GitHub Environment named github-pages
.
Configuring Docusaurus
Generate a Docusuarus website using the following command:
yarn create docusaurus <folder-name> classic --typescript
Make the following changes to the docusaurus.config.js
configuration file:
-
Create the constants
organizationName
andprojectName
const organizationName = "<github-organization-name>"; const projectName = "<repository-name>";
-
Set the URL
const config = { // (...) url: `https://${organizationName}.github.io`, }; const baseUrl = /${projectName}/`;
-
Configure the base URL
const config = { // (...) baseUrl: `/${projectName}/`, };
-
Set the
organizationName
andprojectName
optionsconst organizationName = "<github-organization-name>"; const projectName = "<repository-name>"; const config = { // (...) organizationName, projectName, };
-
Configure the blog and docs edit URLs
const config = { // (...) presets: [ [ "classic", /** @type {import('@docusaurus/preset-classic').Options} */ ({ // (...) docs: { // (...) editUrl: `https://github.com/${organizationName}/${projectName}/tree/main/`, }, blog: { // (...) editUrl: `https://github.com/${organizationName}/${projectName}/tree/main/`, }, }), ], ], };
Adding a GitHub Actions deployment workflow
Use a GitHub Actions workflow template for GitHub Pages from the actions/starter-workflows
repository. Place it in .github/workflows/<workflow-name>.yml
.
Add steps for building the website before the GitHub Pages actions are executed and specify the path
to the actions/upload-pages-artifact
:
# (...)
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
# π Build steps
- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: 16.x
cache: yarn
- name: Install dependencies
run: yarn install --frozen-lockfile --non-interactive
- name: Build
run: yarn build
# π Build steps
- name: Setup Pages
uses: actions/configure-pages@v1
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# π Specify build output path
path: build
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1