255: Add anchor links to headings

erinysong commented 4 months ago

Ticket

Resolves #255

Changes

Add anchor links to Headers 2-6.
Underline anchor linked headers on hover.
Remove special characters from all anchor links. This can also be adjusted flexibly in the future if necessary.

Accessibility Anchor link text aligns closely with actual header text. Anchor link format matches the same style as MDN and HTTP Archive.

Miscellaneous Notes

Anchor links currently do not include icons but the library we use to anchor our headers allow flexible options for anchor link format.
Anchor links only jump to the clicked header and do not automatically copy the link to the clipboard (the user must manually copy the URL in order to copy the link URL). If we want our anchor links to also copy to clipboard, I can update this PR to do so.

Context for reviewers

Setup

Sandbox testing Anchor links can be tested on pages populating the Help page, About page, and Domains page.

Go to this PR's cloud pages site and test that clicking on any h2-h6 headers successfully jumps to the clicked header and updates the URL with the header's anchor link, usually the header's title text though some exceptions exist (e.g., we maintain Help FAQ renaming long headers' anchor links to shorter keywords summarizing the question)
Test that the navigation menu also correctly navigates the user to the correct anchor linked header.

Local testing Test that the above sandbox testing also succeeds in the local environment.

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

[x] Met the acceptance criteria, or will meet them in a subsequent PR
[ ] Created/modified automated tests
[x] Added at least 2 developers as PR reviewers (only 1 will need to approve)
[x] Messaged on Slack or in standup to notify the team that a PR is ready for review
[ ] Changes to “how we do things” are documented in READMEs and or onboarding guide
[ ] If any model was updated to modify/add/delete columns, makemigrations was ran and the assoicated migrations file has been commited.

Ensured code standards are met (Original Developer)

[ ] All new functions and methods are commented using plain language
[ ] Did dependency updates in Pipfile also get changed in requirements.txt?
[ ] Interactions with external systems are wrapped in try/except
[ ] Error handling exists for unusual or missing values

Validated user-facing changes (if applicable)

[ ] New pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
[ ] Checked keyboard navigability
[ ] Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
[ ] Add at least 1 designer as PR reviewer

As a code reviewer, I have

Reviewed, tested, and left feedback about the changes

[ ] Pulled this branch locally and tested it
[ ] Reviewed this code and left comments
[ ] Checked that all code is adequately covered by tests
[ ] Made it clear which comments need to be addressed before this work is merged
[ ] If any model was updated to modify/add/delete columns, makemigrations was ran and the assoicated migrations file has been commited.

Ensured code standards are met (Code reviewer)

[ ] All new functions and methods are commented using plain language
[ ] Interactions with external systems are wrapped in try/except
[ ] Error handling exists for unusual or missing values
[ ] (Rarely needed) Did dependency updates in Pipfile also get changed in requirements.txt?

Validated user-facing changes as a developer

[ ] New pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
[ ] Checked keyboard navigability
[ ] Meets all designs and user flows provided by design/product
[ ] Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
[ ] Tested with multiple browsers, the suggestion is to use ones that the developer didn't (check off which ones were used)
- [ ] Chrome
- [ ] Microsoft Edge
- [ ] FireFox
- [ ] Safari
[ ] (Rarely needed) Tested as both an analyst and applicant user

Note: Multiple code reviewers can share the checklists above, a second reviewers should not make a duplicate checklist

As a designer reviewer, I have

Verified that the changes match the design intention

[ ] Checked that the design translated visually
[ ] Checked behavior
[ ] Checked different states (empty, one, some, error)
[ ] Checked for landmarks, page heading structure, and links
[ ] Tried to break the intended flow

Validated user-facing changes as a designer

[ ] Checked keyboard navigability
[ ] Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
[ ] Tested with multiple browsers (check off which ones were used)
- [ ] Chrome
- [ ] Microsoft Edge
- [ ] FireFox
- [ ] Safari
[ ] (Rarely needed) Tested as both an analyst and applicant user

Screenshots

erinysong commented 4 months ago

@rileyorr Thank you for the feedback and that's a great suggestion on the contraction words! It's a light change from just editing the link name of those specific headers, so I can push a change right now to update those!

erinysong commented 4 months ago

Just pushed an update to our headers with contractions! In case it's helpful to put it here, if we want to customize the URLs for headers, we would format them using the following:

Before: Default Header ## Header Name

After: Customize Header URL ## Header Name {#custom-url-name}

This is the standard way to change URL's in markdown, and the library we use to generate anchor links for our headers also accepts this format to infer that we want to override any default anchor link formatting for a header

cisagov / get.gov