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.

Sign up for GitHub

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

Some exception that might not work #31639

Merged
merged 9 commits into from
Mar 25, 2024
Merged

Some exception that might not work #31639

Changes from 6 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c418b3b
Some exception that might not work
JJ Feb 14, 2024
0e5b039
Couple of typos :recycle:
JJ Feb 14, 2024
ab6c9f1
Improve text
JJ Feb 14, 2024
ea08ecf
Even better :recycle:
JJ Feb 14, 2024
d6fcbb8
Merge branch 'main' into patch-3
JJ Feb 14, 2024
ed44eb0
Merge branch 'main' into patch-3
JJ Feb 15, 2024
5f41504
Update data/reusables/repositories/relative-links.md
JJ Mar 22, 2024
f4f59dc
Update relative-links.md
sophietheking Mar 25, 2024
254a260
Merge branch 'main' into patch-3
sophietheking Mar 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions data/reusables/repositories/relative-links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,13 @@ A relative link is a link that is relative to the current file. For example, if

{% 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.

JJ marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/search?q=repo%3Agithub%2Fdocs%20relative-links&type=code

It's used in:

where both instances seem rather general for GitHub Pages–specific issue info.

Any ideas?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Come to think of it, right after line 1 would also make sense.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My point being the context where the reusable renders in the end:

  1. 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

  2. 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?;)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, OK, I see what you mean now. I got to that fragment from

docs/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md

Line 140 in 3ec6e3b

{% data reusables.repositories.relative-links %}
, 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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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…)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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…

Loading