Some exception that might not work #31639
Conversation
Well, I've spent the best part of the morning trying to find out why [this](https://github.com/orgs/community/discussions/108272) happened; I [got to raise this issue](benbalter/jekyll-relative-links#93) but at any rate it's easier to fix the documentation than fixing the issue. The issue should be right around this line https://github.com/benbalter/jekyll-relative-links/blob/9f05f8524cd974fc151d0d960ae3ad2e4935d3c6/lib/jekyll-relative-links/generator.rb#L52, and I might try to fix it some time in the future, but meanwhile I (or someone else) gets around to do it, gets fixed, and deployed downstream to GitHub pages (which is where I use), this little fix can help lost souls like myself save a bit of time, right? Lots of love to you and all the world in this Valentine day!
github-actions
bot
added
the
triage
nguyenalex836
added
content
|
@JJ Thanks so much for opening a PR! I'll get this triaged for review ✨ |
|
|
||
| {% data variables.product.product_name %} will automatically transform your relative link or image path based on whatever branch you're currently on, so that the link or path always works. The path of the link will be relative to the current file. Links starting with `/` will be relative to the repository root. You can use all relative link operands, such as `./` and `../`. | ||
|
|
||
| Please note that using links in this way: | ||
|
|
||
| ```markdown | ||
| [this | ||
| is a perfectly good relative link](folder/relative.md) | ||
| ``` | ||
|
|
||
| might prevent the link to be converted to `folder/relative.html`. Please keep the text link in a single line. | ||
|
|
||
| Relative links are easier for users who clone your repository. Absolute links may not work in clones of your repository - we recommend using relative links to refer to other files within your repository. |
There was a problem hiding this comment.
The added comment seems to relate to an issue with actual Jekyll dependency benbalter/jekyll-relative-links#93 for github.io pages builds, yet the reusable is used in many more contexts, mostly related to rendering (not only) markdown files in github.com repository content.
There was a problem hiding this comment.
https://github.com/search?q=repo%3Agithub%2Fdocs%20relative-links&type=code
It's used in:
- repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md
- get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md
where both instances seem rather general for GitHub Pages–specific issue info.
Any ideas?
There was a problem hiding this comment.
Since it's in the middle of the piece, it's complicated to move it only where it's relevant. One alternative would be to move it out of the piece and into the only place where it's relevant, placing it after the "Relative links" paragraph.
Another option would be doing the same, putting it only where relevant, and moving the "Relative links" sentence to line 3, right after the first sentence.
There was a problem hiding this comment.
Come to think of it, right after line 1 would also make sense.
There was a problem hiding this comment.
My point being the context where the reusable renders in the end:
-
Repositories / Manage repository settings / Customize your repository / About READMEs:
https://docs-31639-23d21f.preview.ghdocs.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes -
Get started / Writing on GitHub / Start writing on GitHub / Basic formatting syntax:
https://docs-31639-23d21f.preview.ghdocs.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links
Since it's Jekyll–specific, esp. a 3rdparty dependency bug–specific, and these are the places to expose it, I can't find a good fit where to mention it — as these seem too generic, and rather GitHub.com–related (if you read the surrounding chapters, mostly mentions READMEs and repository references).
With all the impact this PR has on users not using Jekyll builds, wouldn't fixing the actual cause in the 3rdparty plugin be the easier path?;)
There was a problem hiding this comment.
Ah, OK, I see what you mean now. I got to that fragment from
, which, as you say, is generic for GitHub, not specific for GitHub pages. There's no specific page for relative links in GitHub pages so what I mentioned above does not make a lot of sense. So here's what we could do: move that patch out to that specific page, clarifying that it will happen only when generating GitHub pages. Would that be acceptable?There was a problem hiding this comment.
https://pages.github.com/versions/ indicates using v0.6.1 that's one version (and couple years) behind the currently released version so who knows 🤷
(Quickly glancing the changes in the plugin, my bet is that the link handling in GFM/cmark-gfm and jekyll-relative-links differ anyways, so there might be way more discrepancies than this one reported…)
There was a problem hiding this comment.
https://pages.github.com/versions/ indicates using v0.6.1 that's one version (and couple years) behind the currently released version so who knows 🤷
Exactly my point... I know introducing "temporary" documentation changes for mitigating a bug elsewhere is, at the end of the day, technical debt. I promise I'll set a watch there and come back here and delete what I created when it's fixed.
I had a quick look through the code, but besides involving Ruby, I gathered that it involved a certain amount of refactoring involving what was or was not considered a link, so I quickly left...
There was a problem hiding this comment.
TL;DR you don't get GFM features from GitHub.com 1:1 in GitHub Pages these days, incl. the newly launched callout syntax et al. even though it uses the same cmark-gfm in the end (but probably not the same version through all the dependencies involved) see: community/16925
With Pages stuck on Jekyll 3.9.x and building newer Jekyll 4+ stacks recommended to be done via custom Actions I can only tell that the disparity of launched features and their absence in GitHub Pages like community/13761 is only going to grow.
Maybe a general note that while the docs cover github.com, the github.io has a different scope and may not support the same features.
There was a problem hiding this comment.
@JJ FYI there's some limitation in compatibility as the jekyll-relative-links was even reverted from 0.7.0 back to 0.6.1 github/pages-gem#910 — so who knows if there's an update path in the near future anyways…
|
|
||
| {% data variables.product.product_name %} will automatically transform your relative link or image path based on whatever branch you're currently on, so that the link or path always works. The path of the link will be relative to the current file. Links starting with `/` will be relative to the repository root. You can use all relative link operands, such as `./` and `../`. | ||
|
|
||
| Please note that using links in this way: | ||
|
|
||
| ```markdown | ||
| [this | ||
| is a perfectly good relative link](folder/relative.md) | ||
| ``` | ||
|
|
||
| might prevent the link to be converted to `folder/relative.html`. Please keep the text link in a single line. | ||
|
|
||
| Relative links are easier for users who clone your repository. Absolute links may not work in clones of your repository - we recommend using relative links to refer to other files within your repository. |
There was a problem hiding this comment.
Come to think of it, right after line 1 would also make sense.
There was a problem hiding this comment.
@JJ 👋 Thanks for opening this PR and contributing to our Docs, we really appreciate it! 💖 I've left a suggestion that updates the wording and moves the explanation to above the example. Would love to hear your thoughts!
nguyenalex836
removed
the
waiting for review
It's absolutely perfect. Thanks! Co-authored-by: Sophie <[email protected]>
|
Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues ⚡ |
Why:
Well, I've spent the best part of the morning trying to find out why this happened; I got to raise this issue but at any rate it's easier to fix the documentation than fixing the issue. The issue should be right around this line https://github.com/benbalter/jekyll-relative-links/blob/9f05f8524cd974fc151d0d960ae3ad2e4935d3c6/lib/jekyll-relative-links/generator.rb#L52, and I might try to fix it some time in the future, but meanwhile I (or someone else) gets around to do it, gets fixed, and deployed downstream to GitHub pages (which is where I use), this little fix can help lost souls like myself save a bit of time, right? Lots of love to you and all the world in this Valentine day!
Closes:
Does not really close, but mitigates benbalter/jekyll-relative-links#93
What's being changed (if available, include any code snippets, screenshots, or gifs):
Just adding an exception to the example.
Check off the following:
I have reviewed my changes in staging, available via the View deployment link in this PR's timeline (this link will be available after opening the PR).
datadirectory.For content changes, I have completed the self-review checklist.