Feature request

Docsify does not use semantic HTML or assign role attributes properly. This introduces accessibility issues by preventing screen readers from identifying and navigating directly to important areas like the main content and site navigation.

Fortunately, these issues can be address easily and in a non-breaking way by assigning appropriate WAI-ARIA roles to existing elements. If breaking changes are permitted, it would be preferable to revisit Docsify's DOM structure and use of HTML tags which would reduce the need to assign role attributes.

Problem or desire

• The <main> element is improperly used as a wrapper for the sidebar, the sidebar toggle button, and the main content. As a result, screen readers are are unable to navigate directly to the main page content.
• The sidebar navigation acts as the site's primary navigation, however it is not rendered with a <nav> element or assigned a role of navigation. As a result, screen readers are unable to navigate directly to the site's primary navigation.
• The top navigation is rendered using a <nav> element and no other element has been assigned a role of navigation. As a result, screen readers 1) improperly identify the top navigation as the site's primary navigation and 2) are unable to identify/navigate directly to any site navigation when the top nav is not rendered.
• The site name/logo is contained with an <h1> element. As a result, screen readers incorrectly identify this is a level one heading instead of a site banner which typically contains the site name/logo. Rendering as an H1 also presents multiple level one headings in the document structure which, while technically valid, is confusing for users.
• The progress bar is rendered as a <div class="progress"> element. As a result, screen readers are unable to detect or announce progress updates.
• The cover page container lacks a meaningful role attribute. As a result, screen readers are unable to identify the type of content it contains.
• The search plugin is rendered without role="search", does not render search progress on the screen, and uses a <div> element without role="button" as a clear button button. As a result, screen readers are unable to identify and navigate directly to the landmark search functionality, provide meaningful search progress feedback to screen readers, or indicate to screen readers that a clear button exists.

Proposal

For the main content:

• Option 1 (non-breaking): Add role="main" to Docsify's <article id="main"> element and role="none" to the <main> element.
• Option 2 (breaking): Move sidebar and sidebar toggle elements outside of <main> element and remove unnecessary "main" ID and wrapper elements like <section class="content">.

For the sidebar / primary navigation:

• Add role="none" to the <aside class="sidebar"> element.
• Option 1 (non-breaking): Add role="navigation" and aria-label="primary" to the <div class="sidebar-nav"> element.
• Option 2 (breaking): Replace the <div class="sidebar-nav"> element with a <nav aria-label="primary"> element.

For the top navigation:

• Option 1 (non-breaking): Add aria-label="secondary" to the <nav class="app-nav"> element.

For the site name/logo:

• Option 1 (breaking): Wrap the site name/log in a <header> instead of <h1>, then wrap the site name/logo and the search feature within a <banner> element.

For the progress bar:

• Option 1 (non-breaking): Add role="progressbar" and related aria attributes to the <div class="progress"> element.
• Option 2 (breaking): Replace <div class="progress"> with a <progress> element.

For the cover page:

• Option 1 (non-breaking): Add role="complementary" and aria-label="cover" to the <section class="cover"> element.
• Option 2 (breaking): Replace the <section class="cover"> with <aside class="cover">

For the search plugin:

• Add a new <div class="results-status" aria-live="polite"> element to provide search progress feedback.
• Add aria-label="search result N" to each <div class="matching-post"> element.
• Option 1 (non-breaking): Add role="search" to the <div class="search"> element.
• Option 2 (breaking): See additional accessible search form guidance here: https://www.a11ymatters.com/pattern/accessible-search/.

Implementation

See above.