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.

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

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

Open
1 task
dodexahedron opened this issue Jun 17, 2024 · 9 comments · May be fixed by #33531
Open
1 task

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

dodexahedron opened this issue Jun 17, 2024 · 9 comments · May be fixed by #33531
Labels
content This issue or pull request belongs to the Docs Content team get started Content related to "Getting Started" doc set

Comments

@dodexahedron
Copy link

dodexahedron commented Jun 17, 2024

Code of Conduct

What article on docs.github.com is affected?

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

What part(s) of the article would you like to see updated?

For the Section links section:

The information in that section doesn't actually explain how the feature works or behaves. It only mentions one method to get the URL for an already-rendered section link in a document.

New section for custom anchors:

Custom anchors are allowed in GitHub markdown documents.
For precedent, explicit custom anchor tags are quite common in a lot of Microsoft Learn documents.

Proposal:

I have a PR drafted and ready to submit after I submit this issue, containing two (initial) commits:

  • One is a proposal for expansion of the Section links reusable, adding detail about how the feature works and an example that showcases several of the behaviors described.
  • The other is a proposal for addition of a new Custom anchors reusable, and the addition of a Custom anchors section below the other links sections of the Basic Writing and Formatting Syntax document

Additional information

No response

Tasks

  1. content get started waiting for review
@dodexahedron dodexahedron added the content This issue or pull request belongs to the Docs Content team label Jun 17, 2024
Copy link

welcome bot commented Jun 17, 2024

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

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

Additional commits were added to address changes requested by the linter workflows, as well as a minor sentence structure tweak to a tip callout.

@dodexahedron
Copy link
Author

All workflow checks passing as of 2ab55df.

Changes are viewable in the preview deployment here (section links) and here (custom anchors).

Going through the self-review checklist now.

@dodexahedron

This comment was marked as resolved.

@dodexahedron

This comment was marked as outdated.

@dodexahedron
Copy link
Author

octothorpe woot

Checks passing again and I'm done making edits unless there's anything y'all want me to address.

Previews look and behave as intended, as far as I can tell.

#33531 is ready for review for real, this time.

One thought I had, while going through the style guide, is that the links section, both before these changes, but now especially after them, would match the style guide better if there were a section ToC, as well as if h3 an h4 headers were used. I opted not to implement that guideline, however, as the rest of the containing document does not follow that guideline, either, so it seemed better to conform to the document's de facto style, instead.

@nguyenalex836 nguyenalex836 added get started Content related to "Getting Started" doc set and removed triage Do not begin working on this issue until triaged by the team labels Jun 18, 2024
@nguyenalex836
Copy link
Contributor

@dodexahedron Thank you for opening an issue and linking it to your PR! ✨

@dodexahedron
Copy link
Author

Glad to help.

I take it that the posted procedures are taken as mere suggestions with some frequency, then? 😅

@nguyenalex836
Copy link
Contributor

@dodexahedron The little things are always appreciated 💛

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content This issue or pull request belongs to the Docs Content team get started Content related to "Getting Started" doc set
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants