Update table markdown guidance #149
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
|
||
| - Centre: `|:---:|` | ||
| - Right: `|---:|` | ||
|
|
||
| Add more columns and rows as needed. | ||
| If a table has three or more columns, you likely need to set a row header in addition to the column headers. Setting a row header improves the experience for screen reader users, as it reduces the amount of information they need to remember while navigating the table. |
There was a problem hiding this comment.
- Style point: "three" => "3".
- Recommend rephrasing "you likely need to" to "you might need to"
- Recommend adding a link to the W3 accessibility tutorials on tables at https://www.w3.org/WAI/tutorials/tables/ for more information to help people decide if they need to add a row header.
There was a problem hiding this comment.
Thanks for the review 👍 I've pushed up an amended commit.
jonathanglassman
suggested changes
Mar 29, 2021
There was a problem hiding this comment.
Content looks good overall @ChrisBAshton. I've commented on a few specific things.
This removes the requirement to add a `<div>` above and below tables. This was originally required because omitting them would break the table completely, but this no longer seems to be an issue. The spacing between the table and the surrounding content is now slightly reduced as a result, but this should be fixed with CSS in the tech docs gem, rather than with non-semantic content. This commit also documents new accessibility guidance whereby tables with 3 or more columns need a row header, introduced in alphagov/tech-docs-gem#214. While I'm here, I've updated the markdown example to use padded cells for horizontal alignment, which is good practice if there is room to do so. I've also omitted the `|:---|` left-alignment instruction, since cells are left-aligned by default. Most markdown table examples you'll come across in the wild use the default `|---|` separator.
jonathanglassman
approved these changes
Mar 29, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This removes the requirement to add a
<div>above and below tables. This was originally required because omitting them would break the table completely, but this no longer seems to be an issue. The spacing between the table and the surrounding content is now slightly reduced as a result, but this should be fixed with CSS in the tech docs gem, rather than with non-semantic content.This commit also documents new accessibility guidance whereby tables with 3 or more columns need a row header, introduced in alphagov/tech-docs-gem#214.
While I'm here, I've updated the markdown example to use padded cells for horizontal alignment, which is good practice if there is room to do so. I've also omitted the
|:---|left-alignment instruction, since cells are left-aligned by default. Most markdown table examples you'll come across in the wild use the default|---|separator.Context
Changes proposed in this pull request
Guidance to review