I'm going to suggest a few small changes here to align better with the other sections:

Having read the sentence before this line, I think we need to explain about automatically generated anchors earlier.

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

I think we can omit these bullets because you've already explained how we process characters that would otherwise need to be encoded this way.

Better to omit as it's not always the case. In wiki the links do not strip any nonASCII chars, but rather do "HTML-safe" i.e. url encode all chars outside of the lower ASCII, both "á" and "ř" get escaped as a multibyte 🤷

Room for simplification here:

Adding a note based on the caution below:

For accessibility reasons, we don't use bold in this way. It also seems as if we don't tend to use the text "Examples" in this document, so I suggest we delete this line.

This is a great point and well worth making.

However, it doesn't qualify as a caution in the user docs because the content includes descriptions of how to delete repositories and cause major problems in an enterprise server version. We keep caution for actions that have permanent implications (see Caution).

I think it would be more helpful to users to add a note earlier in this section about the need for care when linking to autogenerated anchors, so I've added a suggestion there in place of this.

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

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.

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.

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.

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

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

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.

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.

Replacing with name to align with the information on contributing to GitHub docs.

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