Recent PR 100 or 101 changed rendered URL to an HTTP 404

[nathan-at-least]

What is the problem?

The public url for rendered content, https://electric-coin-company.github.io/tfl-book/, is showing a 404.

The original #100 broke the merge & rendering CI automation by failing to include the new mdbook-linkcheck dependency. This was fixed in #100 via this commit prior to merge.

The Render Site actions seem to have succeeded for PR #100 action and PR #101 action.

So it's a mystery why the site is returning a 404.

Do you recommend a solution?

Determine the root cause of the 404 and fix it.

Also, see if we can add any documentation or other safety checks to prevent a similar future category of issues.

[nathan-at-least]

Solution

Ensure the rendered html ends up in ./docs since it moved to ./docs/html with the introduction of [output.linkcheck] to book.toml.

Investigation

As I was investigating the gh-pages branch locally, I noticed this output:

$ git status
On branch gh-pages
Your branch is up to date with 'upstream/gh-pages'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        docs/html/
        docs/linkcheck/

nothing added to commit but untracked files present (use "git add" to track)

$ cat .gitignore

The automation removes ignores, then commits the rendered output. My local filesystem had ./docs/html and ./docs/linkcheck whereas these aren't tracked in the gh-pages branch (commit 9220f01).

I verified that this URL does render:

https://electric-coin-company.github.io/tfl-book/html/

So I believe when adding the [output.linkcheck] to the book.toml, the generated output files changed from html going directly into ./docs to each output plugin going into ./docs/<OUTPUT PLUGIN NAME>. So maybe mdbook omits the <OUTPUT PLUGIN NAME> if there is only one, else it includes that hierarchy.

But then I realized I was on an older revision of gh-pages because I forget to git fetch, so I updated to commit b93489c. So it was a happy accident that I saw the .gitignore discrepancy between local and remote in the first place. ;-)

[nathan-at-least]

Attempted solution #103 did not fully fix this, because it seems github.io won't follow a docs/ symlink.

[nathan-at-least]

Fully fixed via #104.