dodexahedron commented 3 months ago

Code of Conduct

[X] I have read and agree to the GitHub Docs project's 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
- [ ] https://github.com/github/docs/pull/33531

welcome[bot] commented 3 months ago

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.

dodexahedron commented 3 months ago

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 commented 3 months ago

All workflow checks passing as of 2ab55df1437be4f9f959bf41ce3530ea33ff1769.

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

Going through the self-review checklist now.

dodexahedron commented 3 months ago

Ready for review.

Current linter errors being thrown were not from my changes and aren't even in the same area of the docs.

Linter does not throw any errors when run locally:

> npm run lint-content -- --paths data\reusables\repositories\section-links.md

> lint-content
> node src/content-linter/scripts/lint-content.js --paths data\reusables\repositories\section-links.md

.   Running content linter

data\reusables\repositories\section-links.md

    WARNING
    Rule        GHD030, code-fence-line-length Code fence lines should not exceed a maximum length
    Detail      Code fence line exceeds 60 characters.
    Line        39 A link to that section: [Link Text](#thisll--be-a-helpful-section-about-the-g…
    Line        53 Link to the second section: [Name](#this-text-is-the-same-1).

ℹ 🕦 Markdownlint finished in 65.0 ms
⚠ Found 1 file with warning
✔ No errors found

> npm run lint-content -- --paths .\data\reusables\repositories\custom-anchors.md

> lint-content
> node src/content-linter/scripts/lint-content.js --paths .\data\reusables\repositories\custom-anchors.md

.   Running content linter

data\reusables\repositories\custom-anchors.md

    WARNING
    Rule        GHD030, code-fence-line-length Code fence lines should not exceed a maximum length
    Detail      Code fence line exceeds 60 characters.
    Line        16 Some text I want to provide a direct link to, but which doesn't have its own …

ℹ 🕦 Markdownlint finished in 87.0 ms
⚠ Found 1 file with warning
✔ No errors found

> 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

> lint-content
> node src/content-linter/scripts/lint-content.js --paths .\content\get-started\writing-on-github\getting-started-with-writing-and-formatting-on-github\basic-writing-and-formatting-syntax.md

.   Running content linter

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

    WARNING
    Rule        GHD030, code-fence-line-length Code fence lines should not exceed a maximum length
    Detail      Code fence line exceeds 60 characters.
    Line        69 Use `git status` to list all new or modified files that haven't yet been comm…
    Line        96 The background color is `#ffffff` for light mode and `#000000` for dark mode.
    Line        327 [^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
    Line        355 > Useful information that users should know, even when skimming content.
    Line        364 > Urgent info that needs immediate user attention to avoid problems.
    Line        367 > Advises about risks or negative outcomes of certain actions.
    Line        381 <!-- This content will not appear in the rendered Markdown -->

    WARNING
    Rule        GHD033, incorrect-alt-text-length Images alternate text should be between 40-150 characters
    Detail      Image alternate text is 162 characters long.
    Line        24 (col 3) Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers,…
    Detail      Image alternate text is 185 characters long.
    Line        28 (col 3) Screenshot of the README file in the GitHub Docs open source repository with …
    Detail      Image alternate text is 167 characters long.
    Line        56 (col 3) Screenshot of rendered GitHub Markdown showing sample quoted text. The quote …
    Detail      Image alternate text is 184 characters long.
    Line        72 (col 3) Screenshot of rendered GitHub Markdown showing the appearance of characters s…
    Detail      Image alternate text is 173 characters long.
    Line        85 (col 3) Screenshot of rendered GitHub Markdown showing a code block. The words "git s…
    Detail      Image alternate text is 173 characters long.
    Line        99 (col 3) Screenshot of rendered GitHub Markdown showing how HEX values within backtick…
    Detail      Image alternate text is 180 characters long.
    Line        232 (col 3) Screenshot of rendered GitHub Markdown showing a numbered item followed by a …
    Detail      Image alternate text is 203 characters long.
    Line        253 (col 3) Screenshot of rendered GitHub Markdown showing a list item prefaced by the nu…
    Detail      Image alternate text is 177 characters long.
    Line        390 (col 3) Screenshot of rendered GitHub Markdown showing how backslashes prevent the co…

ℹ 🕦 Markdownlint finished in 244.0 ms
⚠ Found 1 file with warning
✔ No errors found

Here are the previews for the modified and added documentation, as of the deployment from my latest commit (04a90034f5473f1d7526f68aacc1cd069d9d8f96), for PR #33531:

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

Any issues just let me know. 😊

dodexahedron commented 3 months ago

I rebased on main again and also made two links relative since they're in reusables.

Waiting on workflows to finish again.

dodexahedron commented 3 months ago

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 commented 3 months ago

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

dodexahedron commented 3 months ago

Glad to help.

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

nguyenalex836 commented 3 months ago

@dodexahedron The little things are always appreciated 💛

github / docs

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

Code of Conduct

What article on docs.github.com is affected?

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

For the `Section links` section:

New section for custom anchors:

Proposal:

Additional information

33531 is ready for review for real, this time.

github / docs

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

Code of Conduct

What article on docs.github.com is affected?

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

For the Section links section:

New section for custom anchors:

Proposal:

Additional information

33531 is ready for review for real, this time.

For the `Section links` section: