Conversation
spikeheap
force-pushed
the
trailing-slash
branch
from
bb868ab to
615ee61
Compare
GitHub pages handles requests differently to the current setup for client-siderouting, which is causing 404 errors if you refresh a page or attempt to visit a URL provided by someone. The site is generated with links that _don't_ have a trailing slash to denote a folder, e.g. `href="/ways-of-working"` when the actual HTML is stored in `/ways-of-working/index.html`. The client-side routing is configured in the same way, so within the site all links work. The build also succeeds because there are no invalid links according to the client-side routing rules. That in itself is not a problem, however GitHub pages doesn't resolve a non-trailing slash path to the `index.html` within the folder. Instead it's looking for content in `/ways-of-working.html`, which doesn't exist. As a result no links that are generated or valid within the Docusaurus Single Page App will resolve when accessed directly in GitHub Pages. This change configures Docusaurus to use trailing slashes for folders, which will change both the way it generates output folders/files _and_ how client side routing works. This _should_ make client and server routing consistent and fix the problem. This hasn't been tested because we don't have a staging environment so the easiest way to validate the fix is to ship it to production and revert it if we don't get the results we want. 1. Visit the playbook.hackey.gov.uk 2. Navigate to Ways of Working 3. Hard refresh or open the same link in a a new window. 4. Validate that the page isn't a 404
spikeheap
force-pushed
the
trailing-slash
branch
from
615ee61 to
3f2f105
Compare
The previous commit changing trailingSlash handling to true introduced some broken links:
```
Exhaustive list of all broken links found:
- Broken link on source page path = /api-playbook/Governance/api_compliance/:
-> linking to ../../api-playbook/ (resolved as: /api-playbook/api-playbook/)
- Broken link on source page path = /api-playbook/Governance/developer_onboarding/:
-> linking to ../../api-specifications/ (resolved as: /api-playbook/api-specifications/)
- Broken link on source page path = /api-playbook/Support/creating_support_doc/:
-> linking to ../../api-playbook/ (resolved as: /api-playbook/api-playbook/)
- Broken link on source page path = /architecture-pillars/Development practices/api_compliance/:
-> linking to ../../api-playbook/ (resolved as: /architecture-pillars/api-playbook/)
- Broken link on source page path = /architecture-pillars/Development practices/developer_onboarding/:
-> linking to ../../ways-of-working/ (resolved as: /architecture-pillars/ways-of-working/)
- Broken link on source page path = /architecture-pillars/Reliability/core_resource_compliance/:
-> linking to ../../api-playbook/ (resolved as: /architecture-pillars/api-playbook/)
```
Fixing these links to point directly to the source markdown file resolves the build failure and lets Docusaurus generate the correct final link (whether it has as trailing slash or not), so this approach is more robust.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
GitHub pages handles requests differently to the current setup for client-siderouting, which is causing 404 errors if you refresh a page or attempt to visit a URL provided by someone.
Why is this happenning?
The site is generated with links that don't have a trailing slash to denote a folder, e.g.
href="/ways-of-working"when the actual HTML is stored in/ways-of-working/index.html. The client-side routing is configured in the same way, so within the site all links work. The build also succeeds because there are no invalid links according to the client-side routing rules.That in itself is not a problem, however GitHub pages doesn't resolve a non-trailing slash path to the
index.htmlwithin the folder. Instead it's looking for content in/ways-of-working.html, which doesn't exist. As a result no links that are generated or valid within the Docusaurus Single Page App will resolve when accessed directly in GitHub Pages.The fix
This change configures Docusaurus to use trailing slashes for folders, which will change both the way it generates output folders/files and how client side routing works.
This should make client and server routing consistent and fix the problem. This hasn't been tested because we don't have a staging environment so the easiest way to validate the fix is to ship it to production and revert it if we don't get the results we want.
Side effects
The change in link handling highlighted a handful of broken links where the build system relied on an assumption about where the file would be. These have been updated to reference the content, which in turn allows Docusaurus to generate the appropriate link depending on how we've configured things. This is more robust and allows for an easier change in hosting provider should we ever consider that.
How to test