Hacker News new | past | comments | ask | show | jobs | submit login
Please support "skip to main content" on your docs site (technicalwriting.dev)
94 points by kaycebasques 51 days ago | hide | past | favorite | 68 comments

I like the general idea... I think it's also a tall ask. When everyone asks for a different feature; there's too many features to implement.

HTML defines a <main> tag: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ma...

> The <main> HTML element represents the dominant content of the <body> of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the central functionality of an application.

(And, yes, the above page has a "Skip to main content" link that shows when I hit tab.)

The thing is, <main> is how the page (via HTML) indicates what the main content is. The browser can have its own keystroke or semantics to find the main content.

What is needed is a combination of practices: widespread adoption of <main> and <nav> tags, but also for search engines to see and respect these. How many times have you searched for some technical issue plus, say, PHP ... only to find that the PHP is really just a word in a set of "related" links, autogenerated by whatever the site is? Were that in a <nav> and that respected by the search engine ...

Until then, skip links aren't the worst idea.

How 'bout real simple browser extensions to add a hotkey to "Scroll to <main>" ?

These skip links reek of hacky workaround. Use semantic html. Demand browsers build the jump into the browser.

Every site implementing this slightly differently is a recipe for future frustration.

Years ago I tried to track down the origin of this practice and at the time all I could come up with was a wishful blog post empathizing with people using screen readers, not an actual user study or formal accessibility research.

What does “demand” mean when applied to free software?

I'm not paying money for them, but they are definitely not free free. I think having my privacy taxed allows some room for demands in the market.

But you are the product, not the market.

What I'd really like is every project documentation has a short "development loop" section. How do the maintainers actually set it up in some kind of development mode, make a change, see the results and be able to iterate on that (and diff/stage the change they made)?

Sometimes, this can be extremely non-obvious and involve a lot of fiddling about, virtual environments, copying files, setting paths or ports etc. Especially when the language or development tooling is unfamiliar. But it's almost insultingly obvious to someone who has developed their workflow for years on the project.

A good example of how not to do it is Sigrok, which has a pile of separate libraries, and instructions on building and installing but not much about whether that's the most effective way to build and debug. Especially as the library you, a prospective hacker, probably want to develop with is a lower-level one to add device support. Eventually you can piece together something, but it often feels like you're not quite doing it "as expected" (or sometimes it's just that fiddly).

A good example is Tridactyl, which has a "build and install it" section, but also has a dedicated "development loop" section that tells you to use "yarn run (re)build && yarn run run"

  On day 1 of this journey I realized how important the Tab key is for website navigation. Tab lets you jump between focusable elements such as links and buttons. If you’re viewing this page from a computer with a keyboard you can try it now [...]
I tried pushing <TAB> and Firefox refuses to do anything with the page. Extremely ironic. I've never experienced a website not being able to do anything with the tab key. For instance, if I push <TAB> right now, Hacker News will navigate me to the "add comment" button. But this website claiming that "a lot of docs sites suck at Tab-based navigation"? Somehow it manages to be the worst I've seen yet.

Just to make sure this is not a Firefox issue, I opened the page in Safari, pushed <TAB>, and nothing happened. At this point I'm not sure if the author is performing some elaborate prank on me. I agree that accessibility is important, and being able to quickly navigate with tabs and arrow keys is something that many modern web apps fail at, but some of them do pretty well! (Slack is surprisingly good at placing focus on the most commonly used widgets of the app, and they even provide a mini tutorial on your first attempt at keyboard navigation).

Assuming that this article is not intentionally breaking keyboard navigation, they should hold themselves to the same standards they have outlined.

Firefox disables tab key navigation on macOS by default.

You can enable it via System Settings -> Keyboard -> 'Keyboard navigation' toggle

Then it works exactly the way the author described (which is also the default on Windows and Linux, I believe)

Thanks for mentioning this. Navigation now works as expected on Firefox, but Safari for some reason still doesn't do anything.

Now I am curious why Mac OS has defaults that seemingly break accessibility on some websites? This is the first time in recent memory that I've experienced a page not responding to tab keys at all. Your suggestion remedied the issue on Firefox, but not on Safari for some reason.

The default shortcut choosen by apple is option+tab (...). You can change it on the preferences of Safari, but not on iPadOS (or I didn't find the way to do it).

Safari requires yet another setting to be toggled in order to allow tabbing between links [1]. Apple is normally at the vanguard when it comes to accessibility, but there are a few legitimate keyboard navigation quirks in Safari.

[1] https://www.mayank.co/blog/safari-focus#keyboard-navigation

> Firefox disables tab key navigation on macOS by default

To be more specific, it only navigates between form elements (including <button>) by default. I was curious why Tab was taking me all over a StackOverflow page but not the one linked here.

The apostrophe key is also very useful, to jump quickly to a particular link.

Unfortunately a lot of websites have no searchable text on their links. Sometimes the problem is that it's an icon; other times the problem is that the text is not added in a way that allows search (I don't HTML enough to know all the ways). This is in addition to all the clickable elements that aren't tabbable, ugh.

I've also found a significant number of scrolling/sliding and menu-like elements where tabbing does weird things (partial scroll, not adjacent, etc.).

I never knew about this, thank you!

Most pages have so many clickable/focusable elements that tab navigation is next to useless.

There was a browser called xxxterm (later called xombrero) that did this pretty nicely. There was a hot key that showed a little overlay of a number on each link. Type that number and it clicks the link.

Sadly the project was discontinued. It was one of my favorite browsers.


Tridactyl does this also. Nyxt does this also.

If you really care about all websites having roughly the same key binding experience then you need to use an extension or custom browser.

It's a really cool feature, I use it everywhere I can: Link Hints extension in browser, EasyMotion in Vim, the "dot" shortcut in elinks, etc.

updated the post to cover browser/OS compat: https://technicalwriting.dev/a11y/skip.html#macos-and-window...

Works fine for me in FF 126.0.1 on desktop Linux.

A11y seems to be caught between "those members of the population who benefit from it, deserve to" and "those members of the population are a tiny portion and the business value is minor vs. the cost". I'd like to hear thoughts from those who have successfully argued against the latter. There's obviously parallels with physical accommodations like ramps and lifts, which it would seem daft to forego in 2024, yet software development prioritisation seems to only care about Business Value.

(Assume I'm talking about for profit software here)

#1. I think when people hear discussion about accessibility, there is an assumption that the only people who benefit are folks who are blind, deaf, or with severe physical impairments requiring a wheelchair.

In fact, web accessibility best-practices also aim to reduce barriers for folks who have e.g. ADHD, autism, dyscalculia, trauma disorders, poor network connections, cheap/low-grade devices, difficulties with mobility and motor control, stroke, color blindness, memory impairments, among many, many others -- ultimately lots, and lots, and lots of people. Also, web accessibility standards cover not only physical and intellectual/cognitive disabilities but also socio-economic and situational impairments (e.g. you're situationally one-handed because you're carrying a baby).

On top of that, it turns out that just as ramps and lifts are quite helpful for nondisabled (situationally or otherwise) folks in many circumstances, so too are websites that don't violate web and accessibility standards by hijacking browser functionality and behave predictably.

#2. The idea that folks have about how "those members of the population are a tiny portion and the business value is minor" is very strange and patently false: the vast majority of people on planet earth will experience disability at some point in their lives. One in ten Americans has a disability, that rises sharply with age to nearly 1 in 2 for older Americans. These aren't difficult stats to find sources for -- so I think this particular argument constitutes a certain level of willful ignorance underlying much of the difficulty disability advocates face.

With respect to your second point, it is grouping a lot of different disabilities together instead of looking at the addition of one affordance for a particular disability.

One point I haven't seen mentioned yet is that a11y provides obvious business value in that it forces devs to write better and more testable code. I first noticed this when using react-testing-library [1], when refactoring my code to be more easily testable became equivalent to adding a11y features.

Example from a project I worked on: I needed to test that when a button is clicked that the app showed a spinner when loading and then the content when the API call completed successfully. The spinner component was just an SVG with no obvious way to select it without adding a test-id, so instead I refactored the app to use an aria-busy attribute [2] in the container where the content is loading. The test then becomes something like this:

  test('shows spinner while loading and content after API call', async () => {
    render(<Example />);

    userEvent.click(screen.getByRole('button', { name: /load content/i }));

    expect(screen.getByRole('main')).toHaveAttribute('aria-busy', 'true');

    await waitFor(() => {
      expect(screen.getByRole('main')).toHaveAttribute('aria-busy', 'false');
      expect(screen.getByText(/content loaded/i)).toBeInTheDocument();
[1] https://testing-library.com/docs/queries/about#priority [2] https://developer.mozilla.org/en-US/docs/Web/Accessibility/A...

My impression is that there are (possibly underenforced) US laws that mandate a certain amount of accessibility - the ADA and possibly others. (I'm 100% not a lawyer, this is not legal advice.)

At a previous job, that was the justification for a mandate to make sure our website and mobile app was accessible prior to its general availability. (It's also the right thing, as we knew, but the existence of a legal requirement tends to give doing the right thing a lot more priority in a team's backlog. So there's at least one case of the law working as designed.)

See also https://en.wikipedia.org/wiki/Americans_with_Disabilities_Ac... -- the experience I'm talking about was prior to the mentioned 9th Circuit ruling or the Supreme Court's 2019 declining of the appeal, but the laws were on the books already. I don't remember exactly whether the Target case is what was mentioned as a motivating factor to us, but it might have been: <https://en.wikipedia.org/wiki/National_Federation_of_the_Bli...>

(I say 'possibly underenforced' because I don't really know enough about the accessibility landscape, but I somehow doubt that every customer unlawfully prevented from accessing services that the ADA covers actually sues...)

Part of ADA compliance comes with applying for a Certificate of Occupancy for your space. If things do not meet minimum satisfaction, they will not issue the CO. If your space is part of a larger building, it'll probably be something to work out with the building itself if there are issues. So comparing it to ramps/rails/parking spaces for ADA is harder as most construction has had that built into it for a long time now, and existing spaces have most likely been retrofitted.

Websites just don't have that level of red tape to launch. People do not need a government issued certificate of minimum level of compliance to launch. There are way too many sites for pretty much any government to monitor for ADA compliance. There's probably a way to report issues, but who has the time to look up where to do that? Some part of my foggy memory also thinks there's a caveat for the size of the company running a website about how strict compliance needs to be, but that might getting confused with cookie banners???

> A11y

This word is inaccessible to those unfamiliar with the abbreviation, such as many non-native speakers who would have difficulty guessing.

Just write "accessibility".

a11y education was just absolutely abysmal when I started learning web development. Even if you had good intentions, figuring out how to make something accessible when you were building out new widgets required a lot of research. I think documentation has gotten a bit better since then, but it still relies on having an engineer that cares enough to bother learning about the topic in the first place.

If you compare Chrome Dev Tools now to what was available 10 years ago, the difference in capabilities was stark. My memory is fuzzy, but I don't think it had support for anything related to accessibility, but over the years they kept adding new features to make it easier to build accessible websites.

I think it's an education gap which can be closed with better tools and documentation.

The thing is, normal html as originally written by humans is already very accessible by default. Only when you cram a bunch of unnecessary content, JS frameworks and reimplement browser elements in software it becomes a problem.

Plenty of places would likely not have put in ramps and lifts if the law didn’t require them to.

I am glad this is mentioned since it is so helpful for screen reader use. It is very handy when using a screen reader to instantly jump to the body of the text with the most semantically relevant info. (So being able to skip certain headers, unnecessary info, navigation bars, etc.) Yes, you can also do this simply by jumping between landmarks but having the ability to instantly jump to the main content reduces friction for non-visual use or helps less-tech literate users who just want to get the main content read.

I think this survey is useful for looking at other preferences of screen reader users (even if it is just one survey) https://webaim.org/projects/screenreadersurvey/

Great resource. Thank you for sharing. Will add to the post.

This might be of interest to anyone interested in similar accessibility features.


"Remove title attribute tooltips."

Well, there goes so many library/plugins that specifically use the title attribute as roll over fly outs.

C-Loftus shared this helpful survey elsewhere in this thread: https://webaim.org/projects/screenreadersurvey/

I feel vaguely aligned with this just because I’m happy to complain about all the extraneous garbage on most sites. But, why does the site start on non-main content in the first place?

It's not about extraneous garbage between the header and main content but rather a way to jump focus directly to the main content for keyboard-navigated browsing.

Consider a large navigation menu appearing before the content in the DOM and having to tab all the way through it to follow a link on every page.

Most stuff starts on marketing fluff nowadays instead of the real meat

Allow me to be the old man screaming at clouds about how a webpage's <body> used to be all the content and nothing but the content.

Now get off my lawn, I miss Web1.0 and 2.0.

The site does show the skp to main content for me using a screen reader. For those using MacOS, you have to change the keyboard navigation method with Option + F7 I think, or go to system settings > keyboard. Originally, Tab only moves to important parts of the window, because MacOS tries so hard to be clever for you.

Honestly, I rarely use skip links, because they sometimes don't even work and just leave my screen reader on the skip link, so I just use headings and landmarks.

In my practice, I've found that the spacebar (or Page Down, for that matter) works for skipping to "main content" about just as well. Unless the site for some reason puts focus into that scrolling "contents of the page" column on the left of the page but thankfully, most sites don't do that and pressing space scrolls down the main page area one page down at a time.

I agree, but 45 years of using emacs has wired into me that my primary navigation tool is search.

Sadly most programs make search a heavyweight operation.

But search at least usually takes me close to what I need from where I can tab as required.

For the author, FYI: I'm running regular Firefox on regular Windows 10. When I open your site link here and first press tab, I do not get a popup for "skip to main content". Instead, it skips the header links entirely and jumps immediately to the hashtag section marker -- not for the first hashtag marker section at the title text, but at the next one labeled "Background". I loaded the site afresh in new tabs and this behavior repeated each time.

When I navigated to the other example accesibility links you provided (such as Google and Wikipedia), the first tab press did jump first to the "jump to content" link.

Thanks, added a note that my implementation doesn't work as expected on Windows. Will dig in later when I can get my hands on a Windows machine.

Alternatively, put your main content above the fold and get rid of that uselessly large hero in the header which necessitates adding skip links.

Is there a name for this idea ? At first I thought it was something which the writer had thought up for themselves but, given the examples from Wikipedia, Google etc, it's clearly an established idea, is there an established term to refer to it by ?

Yes, it’s called a “skip link” or “skip navigation link”:


Thank you.

It would be helpful if the author described the change they made rather than linking off to a patch. It's the "main content" so to speak and I think not all of it is self explanatory.

Added explanation here, thanks for reading https://technicalwriting.dev/a11y/skip.html#implementation

Pretty sure this is also a WCAG requirement! Based on the responses here I'm sure that folks will be surprised how many mainstream sites have this pop up when hitting [tab].

Use Shift + Tab to go back for cases when you unintentionally jump over a link that you want to click so you don't need to tab all the way over all links again.

I definitely agree that sites should have a skip link, but at the same time it feels strange to me that browsers don’t just implement the functionality directly.

Isn’t that the whole point of the <main> tag (and its associated ARIA role), so that browsers can know which content is the “main” content?

Browser only implement what improves ad revenue. How does proper navigation for the end user help ad revenue? It usually reduces the time spent on a page, i.e. it reduces attention, i.e. it reduces ad revenues.

Great idea. The link remain in the page will be the only problem after support "skip to main content" I think the way can't not popular if we don't make the link less enough, We can make it perfect if we make the link as less as possible that in the page, But this is anti trend of development.

If can page can be display in terminal, we can drop the mouse and make all operation on the keyboard.


The solution is to replace 1-dimensional linear tab with 2-dimensional jump navigation where links get short abbreviations, so you can type 2 alpha chars to reach any UI element

Tried it on MacOS with both Firefox and Safari and neither showed a skip to main content button...

There's a bunch of discussion in this thread about browser/OS compatibility. I also just updated the post: https://technicalwriting.dev/a11y/skip.html#macos-and-window...

On firefox I didn't see a skip to main content link when I tabbed through on OSX.

You can do better than the Tab key when navigating a site via keyboard. Install a plugin that creates hotkeys for most actions on a site. I'm thinking of Vimium [1] but I'd guess there are others too.

[1]: https://github.com/philc/vimium

How does one discover that tab opens the skip to main link?

By pressing tab for obvious reasons of trying to navigate through

Tab does not work on safari on osx for the linked site.

Check the macOS and Windows section that I added in response to this thread's comments: https://technicalwriting.dev/a11y/skip.html#macos-and-window...

for keyboard based navigation of web pages I use the "vimium"[1] Firefox add-on. I can highlight every single clickable link on the page with a key combo. Above every highlighted link appears letters that I can type and it'll take me to that link. This has advantages over cycling with Tab bc I can look at any clickable element and click it with 2-3 key strokes.

I mention this bc I've yelled into the void before about not being able to navigate webpages consistently until I stumbled on vimium.

[1] https://addons.mozilla.org/en-GB/firefox/addon/vimium-ff/

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact