255: Add anchor links to headings #296

erinysong · 2024-05-16T17:41:50Z

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

Met the acceptance criteria, or will meet them in a subsequent PR
Created/modified automated tests
Added at least 2 developers as PR reviewers (only 1 will need to approve)
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

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

rileyorr

@erinysong overall this looks great!

The only thing I noticed was when I tested with VoiceOver on the About page's 'What we don't offer' header it read it out as "don T' (dawn tee) instead of 'don't' when I had it read out the url in the url bar. Since we're customizing some of the anchor tags on the FAQ page I wonder if we could write out 'do-not' instead of 'don-t'. Let me know if that's a light lift. Otherwise, looks good to me.

cc @Katherine-Osos in case you have any thoughts on this as well

h-m-f-t

Looks great, works well!

erinysong · 2024-05-20T16:25:25Z

@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 · 2024-05-20T16:41:20Z

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

zandercymatics · 2024-05-28T15:07:03Z

.eleventy.js

+      permalink: markdownItAnchor.permalink.headerLink({ 
+        safariReaderFix: true,
+      }),


(Q) Just out of curiosity, what does this do? I'm unfamiliar with markdownItAnchor

It's a flag built into markdownItAnchor to patch an issue with Safari's browser settings affecting markdown! I believe the developers added it in response to someone posting about the Safari bug

zandercymatics · 2024-05-28T15:08:48Z

_includes/content-blocks/what_we_offer.md

@@ -13,7 +13,7 @@
 - Stay informed about [domain security best practices](../../domains/security).
 - Edit information about your contacts or your domain (like changes to your DNS settings) anytime. 

-### What we don’t offer
+### What we don’t offer {#what-we-do-not-offer}


zandercymatics · 2024-05-28T15:09:51Z

pages/domains/domains_choosing.md

@@ -42,7 +42,7 @@ Avoid using the following in your .gov domain name:
 - [Judicial branch federal agencies](#judicial-branch-federal-agencies)
 - [Legislative branch federal agencies](#legislative-branch-federal-agencies)
 - [Interstate organizations](#interstate-organizations)
- [U.S. states and territories](#u.s.-states-and-territories)
+- [U.S. states and territories](#u-s-states-and-territories)


Suggested change

- [U.S. states and territories](#u-s-states-and-territories)

- [U.S. states and territories](#us-states-and-territories)

I would recommend this instead! At least for me, if I had no context of what this link contained, I'd be confused by the dash separator

I see your point on this! I think the intention behind this was so that screen readers could properly read U.S. as separate letters but can also see how this might introduce more complex anchor links -- since this got design approval I'm assuming that separating US into u-s is effective, but I can defer to @cisagov/gov-designers on their opinion on this

zandercymatics · 2024-05-28T15:10:58Z

pages/domains/domains_eligibility.md

+    - [U.S. Senate](#u-s-senate)
+    - [U.S. House of Representatives](#u-s-house-of-representatives)


Suggested change

- [U.S. Senate](#u-s-senate)

- [U.S. House of Representatives](#u-s-house-of-representatives)

- [U.S. Senate](#us-senate)

- [U.S. House of Representatives](#us-house-of-representatives)

zandercymatics · 2024-05-28T15:11:09Z

pages/domains/domains_eligibility.md

- [U.S. states and territories](#u.s.-states-and-territories)
-    - [States and territories: executive branch](#states-and-territories%3A-executive-branch)
-    - [States and territories: judicial and legislative branches](#states-and-territories%3A-judicial-and-legislative-branches)
+- [U.S. states and territories](#u-s-states-and-territories)


Suggested change

- [U.S. states and territories](#u-s-states-and-territories)

- [U.S. states and territories](#us-states-and-territories)

zandercymatics · 2024-05-28T15:12:04Z

pages/domains/domains_moving.md

 - [Get familiar with domain security best practices](#get-familiar-with-domain-security-best-practices)
 - [Develop a communications plan](#develop-a-communications-plan)
- [Find out if you’re eligible for financial assistance](#find-out-if-you’re-eligible-for-financial-assistance)
+- [Find out if you’re eligible for financial assistance](#find-out-if-you-re-eligible-for-financial-assistance)


Suggested change

- [Find out if you’re eligible for financial assistance](#find-out-if-you-re-eligible-for-financial-assistance)

- [Find out if you’re eligible for financial assistance](#find-out-if-you-are-eligible-for-financial-assistance)

(Nitpick) consistency change with what your doing on words like "won't"

Good catch - thank you for the suggestion!

zandercymatics · 2024-05-28T15:14:06Z

pages/help/help_faq.md

 Since most governments in the U.S. operate transparently, it’s usually not difficult to discover information about an organization. Anyone can easily find the names, roles, or email addresses of those employed, or details like official records, budgets, or a tax ID. However, it can be difficult to know whether someone approaching us actually is who they say they are, or that they really represent their purported organization.

 To prevent someone from using public information to impersonate a government or an official, as well as discourage unauthorized individuals or ineligible organizations from requesting a domain, we verify the identity of new domain requestors using Login.gov. Once your identity has been confirmed, we then conduct a manual review to assess whether you actually work for, or on behalf of, a government.

 Login.gov is a secure, government website that adheres to the highest standards in data protection. Most of the data you submit is not stored. You can learn more about the [privacy and security measures](https://login.gov/policy/){.usa-link--external} taken to keep your information safe.

-<span id="subdomain"></span>
-## Can I request a name like cityname.state.gov (e.g., detroit.mi.gov)?
+## Can I request a name like cityname.state.gov (e.g., detroit.mi.gov)? {#subdomain}


(Q) Does the slugify library basically add the {#subdomain} functionality where you add the element id at the end like that?

Yes it does! It reads what anchor a user sets in markdown before generating its default slugified anchor and manually set anchors will override the default slugify

zandercymatics · 2024-05-28T15:14:59Z

styles/_uswds-theme-custom-styles.scss

+/* markdown-it-anchor header link styling */
+h1,
+h2,
+h3,
+h4 {
+  .header-anchor {
+    text-decoration-line: none
+  }
+
+  &:hover {
+    .header-anchor {
+      text-decoration-line: underline
+    }
+  }
+}



Nice and simple!

therealslimhsiehdy · 2024-05-30T23:57:53Z

.eleventy.js

+  })
+    .use(markdownItAnchor,{
+      permalink: markdownItAnchor.permalink.headerLink({ 
+        safariReaderFix: true,


Question: Would we need we need this fix for any other browsers / what was the issue that we ran into for Safari's Reader mode? 😅

I don't believe so! I think this is a temporary fix by the markdownItAnchor devs to address a Safari bug so I hopefully don't anticipate any other browser issues, but good point to keep a look at the library for any other accessibility issues they may find in the future

therealslimhsiehdy

Looks good! Giving approval on caveat of adding in Zander's suggested changes (ie the word contraction consistency, etc).

ETA: Looks like there's also a conflict on pages/help/help_faq.md as well

erinysong added 7 commits May 14, 2024 15:42

Add initial anchor links to headers

8678ecd

Add updated anchor links

c0c494c

Add underline on hover

f1ca8e6

Correct navigation menu link on domains page

eafdb72

Correct navigation menu link on domains page

4545b06

Remove slugify from id

9031f1c

Remove unused id attribute from slugified links

4c2beb8

erinysong requested review from h-m-f-t, therealslimhsiehdy, CocoByte, rachidatecs, dave-kennedy-ecs, zandercymatics and a team May 16, 2024 17:58

erinysong added 4 commits May 16, 2024 11:05

Remove periods from .gov anchor links

b68520a

Remove question mark escape characters from nav URLs

851f9c6

Remove apostrophe from nav URLs

e866b89

Update a header label

7daf4c4

rileyorr approved these changes May 17, 2024

View reviewed changes

h-m-f-t approved these changes May 20, 2024

View reviewed changes

Update URLs of headers with contractions

7c4a655

Fix broken nav link

60e67f1

zandercymatics reviewed May 28, 2024

View reviewed changes

therealslimhsiehdy assigned therealslimhsiehdy and zandercymatics May 29, 2024

therealslimhsiehdy reviewed May 30, 2024

View reviewed changes

therealslimhsiehdy approved these changes May 30, 2024

View reviewed changes

Expand contraction on heading anchor

ac21eff

Resolve merge conflict

adc3daf

erinysong merged commit 89e4d9d into main May 31, 2024
4 checks passed

erinysong deleted the es/255-anchor-link-headings branch May 31, 2024 17:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

255: Add anchor links to headings #296

255: Add anchor links to headings #296

erinysong commented May 16, 2024 •

edited

Loading

rileyorr left a comment

h-m-f-t left a comment

erinysong commented May 20, 2024

erinysong commented May 20, 2024

zandercymatics May 28, 2024

erinysong May 31, 2024

zandercymatics May 28, 2024

zandercymatics May 28, 2024

erinysong May 31, 2024 •

edited

Loading

zandercymatics May 28, 2024

zandercymatics May 28, 2024

zandercymatics May 28, 2024

erinysong May 31, 2024

zandercymatics May 28, 2024

erinysong May 31, 2024

zandercymatics May 28, 2024

therealslimhsiehdy May 30, 2024

erinysong May 31, 2024

therealslimhsiehdy left a comment •

edited

Loading

	- [U.S. states and territories](#u-s-states-and-territories)
	- [U.S. states and territories](#us-states-and-territories)

		- [U.S. Senate](#u-s-senate)
		- [U.S. House of Representatives](#u-s-house-of-representatives)

	- [Find out if you’re eligible for financial assistance](#find-out-if-you-re-eligible-for-financial-assistance)
	- [Find out if you’re eligible for financial assistance](#find-out-if-you-are-eligible-for-financial-assistance)

255: Add anchor links to headings #296

255: Add anchor links to headings #296

Conversation

erinysong commented May 16, 2024 • edited Loading

Ticket

Changes

Context for reviewers

Setup

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

Ensured code standards are met (Original Developer)

Validated user-facing changes (if applicable)

As a code reviewer, I have

Reviewed, tested, and left feedback about the changes

Ensured code standards are met (Code reviewer)

Validated user-facing changes as a developer

As a designer reviewer, I have

Verified that the changes match the design intention

Validated user-facing changes as a designer

Screenshots

rileyorr left a comment

Choose a reason for hiding this comment

h-m-f-t left a comment

Choose a reason for hiding this comment

erinysong commented May 20, 2024

erinysong commented May 20, 2024

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

erinysong May 31, 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

therealslimhsiehdy left a comment • edited Loading

Choose a reason for hiding this comment

erinysong commented May 16, 2024 •

edited

Loading

erinysong May 31, 2024 •

edited

Loading

therealslimhsiehdy left a comment •

edited

Loading