docs: add rendering hook and fix broken links #4247
Conversation
ea70dac to
7a85390
Compare
| {{- if (strings.HasPrefix .Destination "http") -}} | ||
| <a href="{{ safe.URL .Destination }}" target="_blank">{{ safe.HTML .Text }}</a> | ||
| {{- else -}} | ||
| <a href="{{ ref .Page .Destination | safe.URL }}">{{ safe.HTML .Text }}</a> |
| @@ -1,4 +1,4 @@ | |||
| baseURL: / | |||
| baseURL: https://distribution.github.io/distribution | |||
There was a problem hiding this comment.
Hmm, this is interesting. What does this change so? Is it to make the GH changes work with the new hooks?
There was a problem hiding this comment.
No, it's actually how this should've been. Think of this as the intended absolute url for the deploy; in local deploy it overrides for dev reasons, but this is supposed to be the end host + url.
|
I just noticed that |
7a85390 to
b193fae
Compare
b193fae to
da6a7d0
Compare
@dvdksn I'm assuming you found the fix? |
|
@milosgajdos yes! |
milosgajdos
left a comment
There was a problem hiding this comment.
LGTM. Can you squash?
PTAL @thaJeztah
Update the formatting of links and add a Markdown render hook for handling relative internal links. Cross-references between markdown files are now resolved the same way in both GitHub and Hugo. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
da6a7d0 to
5e75227
Compare
|
squashed @milosgajdos |
|
Our doc system has got complicated enough that I think we need an overview for developers - can we put a README.md, CONTRIBUTING.md, or BUILDING.md into the docs folder with some basic "how to run locally" type instructions? |
|
Perhaps some docs targets in the makefile too? |
|
Yeah we probably could add a make target or something to make it more discoverable. w.r.t. this PR; I think this PR should make life easier, as contributors can create links "as usual" (the way documents can be linked on GitHub), and those links should work both on GitHub (not as pretty as the generated docs, but "functional") and in the generated docs. |
Jamstah
left a comment
There was a problem hiding this comment.
Makefile and developer doc could be in a separate pr, so green tick for this.
|
Belated, but thanks for the resolution. Also, nice trick for having GH links work- I'll use that in the future ;) |
|
I hate "+1"'s but making an exception here and adding my "+1"; happy that we found a good solution for this!! Kudos to @dvdksn ❤️ |
Replaces fix: documentation broken links in production. #4243
closes fix: documentation broken links in production. #4243
Added a Markdown rendering hook for Hugo to handle relative links like they're handled on GitHub. This means you'll be able to view the source markdown files on GitHub directly and still follow links like they work when viewing the deployed HTML pages.
Fixed broken internal links that weren't being detected before as a result of using absolute links.
Simplified the documentation build steps by setting a static base url in the Hugo configuration.
The third change is optional, but makes things a little bit simpler. Simple is good I think. A side-effect of this change is that docs will be served locally on a sub-path (
localhost:1313/distribution) to mimic the production deployment.