Expand Section Links documentation and add a section for Custom Anchors #33531

dodexahedron · 2024-06-17T05:31:31Z

Why:

The information on section links and how they work doesn't really explain how to use them or how they are made.

Also, custom anchors can be used (and are, in fact, quite common in a lot of Microsoft Learn documents, for precedent), so I added a section for them, as well, in a separate commit.

Closes: #33530

What's being changed (if available, include any code snippets, screenshots, or gifs):

As described in #33530, I have expanded and enhanced the Section links reusable, detailing behavior and usage, as well as added a small section detailing behavior and usage of custom anchor tags.

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).
- For content changes, you will also see an automatically generated comment with links directly to pages you've modified. The comment won't appear if your PR only edits files in the data directory.
For content changes, I have completed the self-review checklist.

welcome · 2024-06-17T05:31:34Z

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

github-actions · 2024-06-17T05:36:27Z

Automatically generated comment ℹ️

This comment is automatically generated and will be overwritten every time changes are committed to this branch.

The table contains an overview of files in the content directory that have been changed in this pull request. It's provided to make it easy to review your changes on the staging site. Please note that changes to the data directory will not show up in this table.

Content directory changes

You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request.

Source	Preview	Production	What Changed
`get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md`	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10
`repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md`	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10

fpt: Free, Pro, Team
ghec: GitHub Enterprise Cloud
ghes: GitHub Enterprise Server

dodexahedron · 2024-06-17T08:19:05Z

Re-based on master.

If checks pass and it looks good to me in the preview environment, I'll be ready to submit this for review.

dodexahedron · 2024-06-17T08:21:27Z

Re-pushed from my local environment to sign the commits.

dodexahedron · 2024-06-17T08:23:13Z

Once more, with feeling...

dodexahedron · 2024-06-17T08:35:44Z

Those linter errors for broken links don't have anything to do with my changes, as they're in completely unrelated files. Linter does not throw any errors when run locally as npm run lint-content -- --paths .\content\get-started\writing-on-github\getting-started-with-writing-and-formatting-on-github\basic-writing-and-formatting-syntax.md

Here are the previews for the modified and added documentation:

https://docs-33531-114a4a.preview.ghdocs.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links

https://docs-33531-114a4a.preview.ghdocs.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#custom-anchors

This is ready for review.

dodexahedron · 2024-06-17T08:47:26Z

Hm. I should probably make the section link I added to the #headings section a relative link rather than just an anchor target.

Stand by...

…able

* Additional examples added. * Modified language to align more closely with the style guide. * More specific details about auto-naming rules.

…let listin the

dodexahedron · 2024-06-17T08:54:57Z

Links are now relative.

Let's see how this goes...

dodexahedron · 2024-06-22T03:52:51Z

My pleasure.

Any requests/thoughts/ideas/rude commentary, just let me know!

felicitymay

Hi @dodexahedron - I want to start by thanking you for your patience. It seems as if your PR must have slipped through the cracks 🙈

I also want to let you know how much we appreciate the thought you put into following our style, creating a reusable, and matching the existing content 💖

This is a useful addition to the articles with some great examples. Thank you 🚀

I've added quite a few comments which I'll leave for a few days in case you're interested to see why I'm suggesting changes. Then I'll commit those changes, check that the preview still looks okay and merge your pull request.

I hope that the delay in getting a review for this work doesn't put you off contributing in the future.

data/reusables/repositories/custom-anchors.md

data/reusables/repositories/section-links.md

felicitymay · 2024-08-15T19:30:49Z

data/reusables/repositories/section-links.md

+ * Generated identifiers are UTF-8 URI fragments.
+    * See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5).


🤔 I'm curious about what additional information this reference adds for users. Unless you have a good reason for including it, I'd be inclined to delete these two lines.

data/reusables/repositories/section-links.md

janbrasna

I see the reusable doesn't get added to all the places the neighboring content is used (Q: couldn't this content be covered in one of the existing reusables/chapters where it contextually belongs perhaps?), and more importantly I'm not really sure id is the best attribute for this — that along with classes gets sanitized in many places, so this being a general markdown reference for all the places that accept markdown input I'd say name is a more bulletproof anchor target for this.

janbrasna · 2024-08-15T17:20:30Z

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


 {% data reusables.repositories.relative-links %}

+## Custom anchors
+
+{% data reusables.repositories.custom-anchors %}
+


does only one use/occurrence warrant a reusable?

adding that info to any of the previous reusables contextually might actually be better, so it gets added to the about-readme docs and other occurrences of the neighboring content too?

or if separate, perhaps add the same chapter with reusable to other place that include the two other reusables, like about-readmes…?

I would say no. However, that's how all of those sections seem to be formed, so I was just following suit. 🤷‍♂️

Q: does it need a separate section, or having that contextually appended to some of the existing content would provide more utility and be included with such reusable to all the places they're being currently included?

Thanks for the discussion @janbrasna 👋🏻

does only one use/occurrence warrant a reusable?

Good point. We usually add a reusable file only if we want to use one or more sentences in more than one location.

I think that this content only needs to be included in the Basic writing and formatting syntax article because it's not something that most people will want to do.

So it would be worth moving the content directly into this article and deleting the reusable.

janbrasna · 2024-08-15T17:25:23Z

data/reusables/repositories/custom-anchors.md

+Use HTML anchor tags (`<a id="unique-anchor-name"></a>`) to create navigation anchor points to any place in the document.
+
+> [!NOTE]
+> Custom anchors will not be included in the document outline/Table of Contents.


the syntax here is more of a general info ("writing on github", i.e. anywhere markdown is supported…), so implying a "document" when that might be post/comment/review is not completely correct. (the reusable gets included in several places/contexts…)

basically headings won't create anchors in comments, while custom named anchors are preserved so can be used as anchors, say even inside collapsed details elements in PR/review etc.

Hm, that's a good catch.

Do you have any thoughts on better wording? I felt the note was important in case people expected the same behavior as octothorpes, but I'm certainly not married to the verbiage.

As a bit of context, one of the things that led me to write this section in the first place is that there are quite a few docs on MS Learn that use anchor tags. I was about to fix some inconsistencies in a couple docs, but it turned into a rabbit hole of following a bunch of anchors and a fair amount of duplicated text.

The place I ultimately landed my focus was on the anchors, partially as something I wanted to both verify and ensure consistency of, since I wanted to fully understand how they were being interpreted and mangled, before getting into the rest of it all. But it wasn't mentioned, so I figured I'd experiment and then document for posterity. 😅

if you e.g. demonstrate the difference between heading links that are not created inside comments, whereas custom anchors are, it'll give you the path to also mention autogenerated ToC for documents won't include them (but in context demonstrating the anchor use is not restricted to just documents but any input that accepts md on the site…)

Thanks for opening this discussion, that's a great point that I overlooked.

We could revise this note to be more general - something like:

Any HTML you include in markdown content is rendered directly. If you include custom anchors for headings in a markdown file, the anchors are not recognized as headings by the markdown processor.

janbrasna · 2024-08-15T17:31:48Z

data/reusables/repositories/custom-anchors.md

+> [!NOTE]
+> Custom anchors will not be included in the document outline/Table of Contents.
+
+Link to custom anchors by using the `id` given to the anchor.


that might get filtered in situations where classes and ids are stripped, but ‹a name="foo"> will still work — not sure whether that's more official, but is definitely preferred, and even the own docs guides use name in examples: https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#adding-anchors-to-preserve-links

(IIRC id gets stripped in wikis, so ‹a› name is a must there.)

or in some contexts there's id="user-content-foo" prepended to it so it's hard to explain beforehand what the value in given md context would be …

that might get filtered in situations where classes and ids are stripped, but ‹a name="foo"> will still work — not sure whether that's more official, but is definitely preferred, and even the own docs guides use name in examples: https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#adding-anchors-to-preserve-links

I did quite a bit of testing to ensure I was documenting actual behavior. The way I wrote it, at least at the time, was what my of course non-exhaustive testing revealed.

Being an undocumented "feature," that's all that was really available for me to do, without being familiar with the pipeline that produces the final rendered content.

My thinking was that, in the course of this PR, a formal behavior could be either gleaned from the source or defined here, to be formally implemented however it is settled upon. Since it's all over the place in other ms learn documents, it seems only fair for it to be documented. 🙂

Adding to that thought, I do kinda think a formal spec for the feature and perhaps even exposure of it in the slash menu or something for didcoverability is warranted.

Otherwise, it's effectively an unsafe-for-public-consumption internal abuse of the markup that IMO shouldn't be used in public open source documents at all. Lead by example and all that. 😅

There are many systems using many renders and formatting libraries used around the site, so there's no formal spec how that behaves once you start going too much into detail (as every place has its own implementation specifics…) — so it's better to be safe and a bit vague;)

(The "id" behav has changed over the past decade, whereas "name" stays consistent, and is used in style guide docs as an example, that's why I'm offering it as a more stable alternative; also not interfering with the rest of the page if one's not too careful…)

I had forgotten that we already have guidance on custom anchors for the GitHub docs site itself 🙈

I agree with @janbrasna that name would be better here. The GitHub docs site is rendered using different process from the content on the GitHub platform, but it will avoid introducing confusion.

The GitHub docs have limited information on the use of HTML in markdown files and fields that accept markdown. My understanding is that this is intentional - we don't want to end up writing an HTML primer, there are lots of those already. However, it sounds as if adding information on custom anchors will be useful to users.

janbrasna · 2024-08-15T17:35:01Z

data/reusables/repositories/section-links.md

+
+> [!CAUTION]
+> Changing the order of sections having headings with the same name will cause their generated identifiers to change, as well, resulting in links to those sections no longer pointing to the same locations they previously pointed to.\
+> Use [Custom anchors](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#custom-anchors) to create anchors that will not be automatically changed.


this will not pass wrt style guide for l10n issues, inline links are not preferable, see the style guide for examples how to link relevant sections, +autotitle use for easier translations.

janbrasna · 2024-08-15T17:36:01Z

data/reusables/repositories/section-links.md

@@ -1,3 +1,58 @@
 You can link directly to a section in a rendered file by hovering over the section heading to expose {% octicon "link" aria-label="the link" %}.

 ![Screenshot of a README for a repository. To the left of a section heading, a link icon is outlined in dark orange.](/assets/images/help/repository/readme-links.png)
+
+[Headings](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) automatically create anchors which have default names created from the text of the heading, with the following rules:


same ref issue as above — i believe both could be avoided if the addition is somehow blended with the existing content, not creating a specific chapter for it…

Yeah I struggled with that part for quite a while and was expecting something to that effect to be part of the feedback.

I wasn't really sure where was most appropriate to say all this stuff, how best to avoid being repetitive, and whether it necessarily belonged together or not, among other things.

Believe it or not, this version is like ⅓ the length of the original I had written up on my local machine before editing it down for commit. 😅

Plus it was I think one of the final parts I wrote, chronologically, so I'm sure there was a bit of fatigue involved. 😆

I'm not attached to any of the content, as written, so definitely don't hold back for sake of my ego or anything. All I want is a good and slightly more complete document, however it ends up. 🙂

janbrasna · 2024-08-16T16:53:22Z

data/reusables/repositories/section-links.md

+ * All other whitespace characters are removed.
+ * Paired formatting markup characters are removed, leaving only their contents (e.g., `_italics_` becomes `italics`).
+ * Punctuation and other characters not allowed in a URI fragment are removed.
+ * Other multi-byte UTF-8 characters which are valid in URI fragments are not modified.


@felicitymay I believe these two bullets would still refer to the RFC syntax for explanation how the string gets transformed (i.e. what's allowed =to stay, and what's not) so this may need a teeny tiny tweaking if removing #33531 (comment)

In that case, I suggest that we provide a set of simple bullets in this article as general guidance, but give the link to the RFC syntax for anyone who wants more detailed information.

janbrasna · 2024-08-16T16:57:00Z

data/reusables/repositories/custom-anchors.md

+```markdown
+# Section Heading
+
+Some body text of this section.
+
+<a id="my-custom-anchor-point"></a>
+Some text I want to provide a direct link to, but which doesn't have its own heading.
+
+...more content...
+
+[A link to that custom anchor](#my-custom-anchor-point)
+```


TL;DR the example is somewhat lengthy to just demonstrate the feature (and lack differentiating / demonstrating the implicit header anchors at the same time); maybe someone from the content/triage could suggest something more to the point?

(if not, at least the ellipsis etc. in the dummy content could be typographically correct?)

I think that's a semi-common issue in that document, as a whole, actually, so I agree and think one or more advanced or details or whatever pages are warranted for various features in that rather large document (including this one).

The github documentation is a bit more monolithic.in a lot of places than other ms learn topics. I don't know if there are any high level goals around consistency between them, organization-wise, but that's just my 2 cents on that specific concept.

That would also aid mobile-friendliness. Github doc pages can be VERY heavy on mobile browsers.

dodexahedron · 2024-08-19T04:33:23Z

Thanks for coming back to it, regardless!

I am just now going through my inbox, so I am just seeing this now and will read it over shortly and address any remaining feedback as soon as I can. 🙂

janbrasna · 2024-08-21T18:12:31Z

data/reusables/repositories/section-links.md

+
+ * Generated identifiers are UTF-8 URI fragments.
+    * See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5).
+ * All ASCII letters are converted to lower-case.


That's too specific to be always true;] Quickly checking, wiki encodes Á (which is ascii) instead of lowercasing it as-is, encoding it as percent/multibyte instead. 🤷

So I'd stay away from referring ASCII, Unicode codepoints, multibyte chars, RFC rules etc. as these can change any day:/ and may differ between readmes/files, Jekyll-built pages, wikis, projects, comments, discussions etc.

data/reusables/repositories/custom-anchors.md

felicitymay · 2024-08-22T11:10:08Z

data/reusables/repositories/custom-anchors.md

+> [!TIP]
+> Custom anchors are not considered by the automatic naming and numbering behavior of automatic heading links.\
+> To avoid ambiguous references, use a unique naming scheme for custom anchors, such as adding a prefix to the `id` attribute value of custom anchors.


We can probably delete this if we expand the note above as suggested 🤔

felicitymay · 2024-08-22T11:19:35Z

@dodexahedron and @janbrasna - thanks for this PR and the interesting discussions ✨

@dodexahedron - I'm not sure if you have the time or desire to wade through all the comments and update your PR or not. Let me know if you want me to have a go. I'm out of the office next week, but would be happy to update the PR when I'm back.

…expansion

Content moved directly into the basic writing article

felicitymay

@dodexahedron - thanks for your patience with this pull request ✨

I've made changes based on the various discussions on the pull request. This looks ready to merge but I'll wait for a few days in case you or any of the other contributors to this discussion have further feedback.

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

...managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md

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

dodexahedron · 2024-09-16T22:22:25Z

Apologies. It fell off my radar, but I'll take a look later this evening, if there's still anything outstanding.

…expansion

janbrasna

Great simplification! Love it. Looks good, I will check the deployed previews how that reads on the output, just a few nits/questions from quickly glancing:

data/reusables/repositories/section-links.md

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

Co-authored-by: Jan Brasna <1784648+janbrasna@users.noreply.github.com>

felicitymay

@dodexahedron and @janbrasna - many thanks for the collaboration on this addition to the basic writing and formatting syntax article 💖

I think this is ready to merge now 🚀

github-actions · 2024-09-23T08:20:57Z

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 ⚡

github-actions bot added the triage Do not begin working on this issue until triaged by the team label Jun 17, 2024

dodexahedron force-pushed the dodexahedron-section-links-and-custom-links-expansion branch from ff2e392 to 7a240a7 Compare June 17, 2024 08:18

dodexahedron force-pushed the dodexahedron-section-links-and-custom-links-expansion branch from 7a240a7 to ff2e392 Compare June 17, 2024 08:20

dodexahedron force-pushed the dodexahedron-section-links-and-custom-links-expansion branch from ff2e392 to 04a9003 Compare June 17, 2024 08:22

dodexahedron marked this pull request as ready for review June 17, 2024 08:34

dodexahedron mentioned this pull request Jun 17, 2024

Add more information on behavior and usage of section links and document custom anchors #33530

Closed

1 task

dodexahedron added 15 commits June 17, 2024 01:54

Add more details, rules, behavior, and examples to section links reus…

00a99ca

…able

Add section for custom anchors

deff51e

Added additional line breaks suggested by the linter

793614a

Add line break at the end of the file, requested by linter

918dc44

Changed list style to use * instead of -

334d6fe

Minor tweaks to the tip text for easier reading.

23f6e59

Modified language to more closely align with the style guide

a1d3e15

Style and content changes

fd1133e

* Additional examples added. * Modified language to align more closely with the style guide. * More specific details about auto-naming rules.

Clarification, re-ordering, language tweaks, and linking to resources

8d3fa36

Add a tip to use custom anchors to address the called-out issue

e617a28

Apparently footnotes aren't allowed there

87aa991

Included the links that were previously added as footnotes to the bul…

c7186fa

…let listin the

Shortened these to make the linter a little happier

afd0ebe

Caution feels more appropriate here.

0eb2910

Make these links relative

49d4159

dodexahedron force-pushed the dodexahedron-section-links-and-custom-links-expansion branch from 04a9003 to 49d4159 Compare June 17, 2024 08:54

felicitymay reviewed Aug 15, 2024

View reviewed changes

janbrasna reviewed Aug 16, 2024

View reviewed changes

This comment was marked as spam.

Sign in to view

This comment was marked as off-topic.

Sign in to view

janbrasna reviewed Aug 21, 2024

View reviewed changes

felicitymay reviewed Aug 22, 2024

View reviewed changes

data/reusables/repositories/custom-anchors.md Outdated Show resolved Hide resolved

felicitymay reviewed Aug 22, 2024

View reviewed changes

felicitymay added 6 commits September 16, 2024 12:30

Apply suggestions from code review

c6c2a56

Merge branch 'main' into dodexahedron-section-links-and-custom-links-…

b7dc34c

…expansion

Updates to address comments part 1

4a085ba

Delete data/reusables/repositories/custom-anchors.md

1096825

Content moved directly into the basic writing article

Update to move the detailed content into the basic writing article

10d9399

Add link to README file for more info

9a691f1

felicitymay reviewed Sep 16, 2024

View reviewed changes

A few minor updates from self-review

09f5d48

Merge branch 'main' into dodexahedron-section-links-and-custom-links-…

f535f75

…expansion

janbrasna reviewed Sep 20, 2024

View reviewed changes

data/reusables/repositories/section-links.md Outdated Show resolved Hide resolved

data/reusables/repositories/section-links.md Outdated Show resolved Hide resolved

janbrasna reviewed Sep 20, 2024

View reviewed changes

...getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md Outdated Show resolved Hide resolved

janbrasna reviewed Sep 20, 2024

View reviewed changes

...getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md Outdated Show resolved Hide resolved

Apply suggestions from code review

db47583

Co-authored-by: Jan Brasna <1784648+janbrasna@users.noreply.github.com>

felicitymay approved these changes Sep 23, 2024

View reviewed changes

felicitymay added this pull request to the merge queue Sep 23, 2024

Merged via the queue into github:main with commit 21058b8 Sep 23, 2024
46 checks passed

		* Generated identifiers are UTF-8 URI fragments.
		* See [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5).

Expand Section Links documentation and add a section for Custom Anchors #33531

Expand Section Links documentation and add a section for Custom Anchors #33531

Conversation

dodexahedron commented Jun 17, 2024 • edited Loading

Why:

What's being changed (if available, include any code snippets, screenshots, or gifs):

Check off the following:

welcome bot commented Jun 17, 2024

github-actions bot commented Jun 17, 2024 • edited Loading

Automatically generated comment ℹ️

Content directory changes

dodexahedron commented Jun 17, 2024

dodexahedron commented Jun 17, 2024

dodexahedron commented Jun 17, 2024

dodexahedron commented Jun 17, 2024

dodexahedron commented Jun 17, 2024

dodexahedron commented Jun 17, 2024

dodexahedron commented Jun 22, 2024

felicitymay left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janbrasna left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

felicitymay Aug 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dodexahedron Aug 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dodexahedron commented Aug 19, 2024

This comment was marked as spam.

This comment was marked as off-topic.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

felicitymay commented Aug 22, 2024

felicitymay left a comment

Choose a reason for hiding this comment

dodexahedron commented Sep 16, 2024

janbrasna left a comment

Choose a reason for hiding this comment

felicitymay left a comment

Choose a reason for hiding this comment

github-actions bot commented Sep 23, 2024

dodexahedron commented Jun 17, 2024 •

edited

Loading

github-actions bot commented Jun 17, 2024 •

edited

Loading

felicitymay Aug 22, 2024 •

edited

Loading

dodexahedron Aug 19, 2024 •

edited

Loading