Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Broken links to some pages in docs #1634

Closed
KyrietS opened this issue May 31, 2021 · 2 comments · Fixed by #1638
Closed

Broken links to some pages in docs #1634

KyrietS opened this issue May 31, 2021 · 2 comments · Fixed by #1638
Assignees

Comments

@KyrietS
Copy link
Member

KyrietS commented May 31, 2021

I've created this issue to track the progress of fixing broken links on some pages.

I can successfully reproduce this weird behaviour:

  1. Go to https://premake.github.io/docs/Developing-Modules/
  2. Links are broken, because they are referencing /docs/Developing-Modules/* instead of /docs/*
  3. Use sidebar navigation and go to Adding a New Action
  4. Use sidebar navigation and go back to Developing Modules
  5. Links are working fine
  6. Refresh the page (F5)
  7. Links are broken again

I will try do debug this but at the moment I suspect that it's Docusaurus' fault.

@Jarod42
Copy link
Contributor

Jarod42 commented May 31, 2021

It seems there is a difference between
https://premake.github.io/docs/Developing-Modules (working)
and
https://premake.github.io/docs/Developing-Modules/ (not working).

@KyrietS
Copy link
Member Author

KyrietS commented May 31, 2021

Similar problem has already been reported: facebook/docusaurus#2317
The solution proposed there seems to work.

So instead of this:

* [Introduction](introducing-modules)
* [Adding Unit Tests](adding-unit-tests)
* [Sharing Your Module](sharing-your-module)
* [Embedding Modules](embedding-modules)

we should always write references to other pages like this:

* [Introduction](Introducing-Modules.md)
* [Adding Unit Tests](Adding-Unit-Tests.md)
* [Sharing Your Module](Sharing-Your-Module.md)
* [Embedding Modules](Embedding-Modules.md)

^ case sensitive!

Fortunately when I was migrating reference pages I always used filenames with *.md extensions. So there aren't many pages left to fix.

In my opinion it's a bug in Docusaurus. They should fix this weird behaviour of breaking links after refresh or mark those links as broken during building process.

Fun fact: I've already advised @starkos how to create links to other pages in my migration notes 😉

When linking to another document ALWAYS use relative path with *.md extension. Docusaurus will generate valid urls, and links will also work when browsing on GitHub. Additionally, you will get a warning message when link to a markdown file can't be resolved.

I'm working on fixing this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants