[FEATURE REQUEST] Add option to generate skip link for screen reader users

[kburk1997]

I am currently using docsify to generate organization documentation for an organization on my school's campus. I've noticed that when using a screen reader to test accessibility, it first tabs through the aside before going to the main content.

The current standard is to add a skip link to the main content.

I've tried adding a skip link manually with no luck, and it appears I have to dig into the docsify code in order to be able to add one.

That being said, an option to generate a skip link will really help with screen reader accessibility for documentation generated through this project.

[trusktr]

Sorry that no one replied to you since 2018! The project is being more actively maintained lately.

I have to dig into the docsify code in order to be able to add one.

It is currently a little difficult to modify the underlying source that generates the markup. Maybe we should change to a component-based system that encapsulates markup in each component.

But more back on topic, this is a good feature to add. @anikethsaha @jhildenbiddle Possible to add this in v4?

[jhildenbiddle]

Based on the comments in #495, the decision back in 2018 was to implement this feature as a third-party plugin. I'm guessing that this never happened given that a "skip link" plugin isn't listed on awesome-docsify.

Accessibility is something we should absolutely consider moving forward and do a better job with in v5. Regarding this particular issue, it's important to realize that the linked document describing best practices for "skip links" was last updated on October 23, 2013. Times have obviously changed since then, and along with them likely accessibility best practices as well. I'm not an accessibility expert so I can't say for certain if "skip links" are still a best practice, so I think we should aim to better understand current best practices before we agree to make changes like these. I propose this not because adding a skip link is difficult (it isn't), but because this issue is just one of many accessibility-related issues that should be addressed with docsify.

For example, consider that docsify currently render no text within the UI. This means docsify core does not have to worry about internationalization/localization. Plugins like full text search do though, so they offer the ability to localize strings using the docsify configuration object:

window.$docsify = {
  search: {
    // Localization
    placeholder: {
      '/zh-cn/': '搜索',
      '/': 'Type to search'
    }
  }
}

Easy enough. We could offer the same for a "skip navigation" link:

window.$docsify = {
  skipLink: {
    '/': 'skip navigation',
    '/es/' : 'omitir navegación',
    '/zn-ch/': '跳过导航'
  },
};

But what if we want to offer multiple "skip" links (which is also considered a best practice):

window.$docsify = {
  localization: {
    skipToMainNavigation: {
      '/': 'skip to main navigation',
      '/es/': 'saltar a la navegación principal',
      '/zn-ch': '跳到主导航'
    },
    skipToSidebarNavigation: {
      '/': 'skip to sidebar navigation',
      '/es/': 'saltar a la barra lateral de navegación',
      '/zn-ch': '跳到侧边栏导航'
    },
    skipToSearch: {
      '/': 'skip to search',
      '/es/': 'saltar a buscar',
      '/zn-ch/': '跳过搜索'
    }
  }
};

Better yet, why not let the users define their own skip links so they can provide better descriptions (e.g. "change language" instead of "skip to main navigation"), set the order, and add/remove links as they see fit?

window.$docsify = {
  skipLinks: {
    // Path
    '/': {
      // UI Text : CSS selector or URL to skip to
      'change language': 'nav',
      'skip to main content': 'main'
    },
    '/es/': {
      'cambiar idioma': 'nav',
      'saltar al contenido principal': 'main'
    },
    '/zn-ch/': {
      '改变语言': 'nav',
      '跳到主要内容': 'main'
    }
  }
};

My intention here is only to show that while adding a single skip link might be relatively easy, we should think through the issue to determine what we want to do first, then work backwards to determine what we can do in the near term. Maybe we land on a vision for v5 (like the last example above) but determine we can implement something simpler (like the first example above) with the confidence on knowing that the current (v4) solution won't interfere with the future (v5) solution.

In the meantime...

@kburk1997 -- Are you still using docsify for your organization? If so, do you still have a need for "skip link" functionality or have you worked around this issue?

[kburk1997]

Apologies for the late reply - I have graduated the university I was attending when I first opened the issue. I have since found another use case for docsify - is there any update on adding a skip link?

[jhildenbiddle]

Thanks for creating the issue and for your patience white waiting for it to be addressed, @kburk1997.

I've created a draft PR here: #2253. In that PR you will find a preview link which will allow you to review the changes:

Before I mark this PR as ready for review by the maintainers, I would love to get your thoughts and/or feedback.

Thanks!