docs: Make README links work if viewed in code repository #99
Conversation
This file contains 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
An unexpected feature of the README-to-GitHub Pages conversion is that any link in the docs/README.md that refers to a **generated** file, will of course appear as 404 if it was clicked from within the code repository. The root of the GitHub pages is generated from README.md, which is of course easy to find (and even displayed automatically by GitHub while navigating the code tree into the docs directory). Generated files are not stored in the repository, so those links only work when the README is viewed as part of the GitHub Pages. The old style works from within the GitHub pages where the generated files actually exist. Specifying an absolute URL for each one feels less future-proof than a relative path, but it needs to be done so that there are not broken links for anyone who finds the README via the code repository tree instead of the GitHub Pages. The links to files that are static (exist already under docs) were left as relative links, since they work in both situations. Signed-off-by: Gunnar Andersson <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Author: Gunnar Andersson <[email protected]>, MBition GmbH.
Confusing links in README.md inside docs/
The links in README.md inside of docs/ work correctly when viewed through GitHub pages, but if someone looked directly at the README in the code repository, the links go to not-yet-generated documentation files, and this was not obvious. Now, by linking directly to the published GitHub pages explicitly, the links will work also when viewed inside of the code repository.
The program was tested solely for our own use cases, which might differ from yours.
The submission is provided under the main project license (LICENSE file in root of project).
Provider Information