Deployment instructions for GitHub Pages (and possibly other destinations too) could be improved

[mattwelke]

I want to leave some feedback about an issue I ran into when following instructions to create a test site and deploy it to GitHub Pages, and what I had to do to fix the issue. For context, I have used Node.js before and I had deployed a static site to GitHub Pages before around 2017, so I was coming into this with some knowledge already and skipping directly to what info I thought I needed.

Basically, my issue came down to me skipping some instructions because I didn't realize I needed to follow them. I didn't realize I needed to set baseUrl. That's because I jumped directly to the GitHub Pages deployment instructions as soon as I saw a link to it in the docs, without first reading the deployment related docs that apply regardless of the destination you deploy to.

Details

I started from https://docusaurus.io/docs. It told me to run commands like npx create-docusaurus@latest my-website classic to create my site. I chose the TypeScript variant. I was able to view my site on localhost:3000 after following the steps on this page. The workflow felt familiar to me because I've used Node.js based static site generators and NPM packages like http-server before. Getting something I could look at at localhost:3000 was how I expected these steps to end.

I then wanted to deploy the site to GitHub Pages. I looked at my repo and noticed that GitHub Pages now has a GitHub Actions workflow in addition to the original workflow where you'd build and push your static files to a particular branch (usually gh-pages) and it would host those files.

GitHub docs had instructions for using the actions workflow in general, and they had preset workflows for some frameworks like Next.js, but no instructions or presets for Docusaurus. I figured I might see a workflow specifically for publishing a Docusaurus site somewhere in the Docusaurus docs, so I went back there. Indeed, I found https://docusaurus.io/docs/deployment.

I noticed in the sidebar on the right that it had the link to https://docusaurus.io/docs/deployment#deploying-to-github-pages, so I went directly there. It told me about how you can have two repos or one. I chose the one repo approach. I figured it was fine because I was using the GitHub Actions way of publishing my site, so I wouldn't be polluting my repo with built files. It would remain just source code files. It told me to edit three properties - projectName, organizationName, and trailingSlash. It left url and baseUrl alone (url as 'https://endiliey.github.io' and baseUrl as '/'). I set those three properties and deployed my site. The properties ended up as this for me:

{
  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',
  organizationName: 'mattwelke',
  projectName: 'docusaurus-test',
  trailingSlash: false
}

It had two workflows I could use, one for publishing the main branch and one for publishing previews upon PRs made to the main branch. This was perfect for me. I used them as is, except for changing them to use NPM as the package manager instead of Yarn, to match the output of me running npx create-docusaurus@latest my-website classic earlier.

My site published successfully, but when I tried to load it at https://mattwelke.github.io/docusaurus-test/, it displayed an error message telling me I'd misconfigured it:

Your Docusaurus site did not load properly.

A very common reason is a wrong site baseUrl configuration.

Current configured baseUrl = / (default value)

We suggest trying baseUrl = /docusaurus-test/

I edited my configuration again, setting baseUrl to '/docusaurus-test'. I left url alone (as 'https://your-docusaurus-site.example.com') because at this point, I hadn't read any instructions to change it. I deployed again, and this time it worked. My site rendered and I was able to click around to the different pages.

Then, when carefully looking at the docs again to see what it said about the baseUrl property, I noticed that at the top of https://docusaurus.io/docs/deployment, under the Configuration section, it talks about the properties url and baseUrl, telling you to set them to specific values. Now I understand that this is the info I skipped that would have prevented my deployment to GitHub Pages from failing.

I think the solution is to make it clear under each specific part of the Deployment docs (e.g. https://docusaurus.io/docs/deployment#deploying-to-github-pages) that there are steps that must first be completed regardless of deployment destination. Users jumping straight to docs they think are relevant to them (like I did here) wouldn't miss this info.

[ilg-ul]

I concur, I also faced similar problems at my first deployments.