Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Convert admonition blockquotes to sections for screen reader users #1938

Merged
merged 16 commits into from
Aug 16, 2024
Merged

Convert admonition blockquotes to sections for screen reader users #1938

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
2813258
Convert admonition blockquotes to divs
voughtdq Aug 10, 2024
dad588b
Fix styles, format code
voughtdq Aug 10, 2024
498b96c
Update admonition styles for epub
voughtdq Aug 10, 2024
7174cb3
Make sure to test for admonition class
voughtdq Aug 12, 2024
263c082
Use section tags for admonitions
voughtdq Aug 12, 2024
7f61e1b
Update print and tabset styles
voughtdq Aug 12, 2024
30dc41b
Simplify section.admonition to .admonition
voughtdq Aug 12, 2024
c586c8e
Simplify admonition styles further
voughtdq Aug 12, 2024
b907d27
Replace .admonition with section.admonition
voughtdq Aug 12, 2024
8f4b5d8
Simplify remaining styles
voughtdq Aug 12, 2024
3888ab0
Add missed selector
voughtdq Aug 13, 2024
89068be
Merge branch 'elixir-lang:main' into accessible-admonitions
voughtdq Aug 13, 2024
0d9ad85
Identifiy admonition headings with a class
voughtdq Aug 15, 2024
bf032c3
Use List.key*/*, re-organize tests
voughtdq Aug 16, 2024
5fd1ca8
Update JS, fix bug caused by missing a CSS selector
voughtdq Aug 16, 2024
7a5ad41
Minor tweak: add " " as second arg to split/2
voughtdq Aug 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions assets/css/content/admonition.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,36 @@
.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition {
border-radius: 10px;
border-left: 0;
}

.content-inner blockquote.warning {
.content-inner section.admonition.warning {
background-color: var(--warningBackground);
}

.content-inner blockquote.error {
.content-inner section.admonition.error {
background-color: var(--errorBackground);
}

.content-inner blockquote.info {
.content-inner section.admonition.info {
background-color: var(--infoBackground);
}

.content-inner blockquote.neutral {
.content-inner section.admonition.neutral {
background-color: var(--neutralBackground);
}

.content-inner blockquote.tip {
.content-inner section.admonition.tip {
background-color: var(--tipBackground);
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition > .admonition-title {
color: var(--contrast);
margin: 0 -1.2rem;
padding: .7rem 1.2rem .7rem 3.3rem;
font-weight: 700;
font-style: normal;
}
.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip)::before {
.content-inner section.admonition > .admonition-title::before {
color: var(--contrast);
position: absolute;
left: 1rem;
Expand All @@ -41,82 +41,82 @@
-moz-osx-font-smoothing: grayscale;
}

.content-inner blockquote :is(h3, h4).warning {
.content-inner section.admonition > .admonition-title.warning {
background-color: var(--warningHeadingBackground);
color: var(--warningHeading);
}
.content-inner blockquote :is(h3, h4).warning::before {
.content-inner section.admonition > .admonition-title.warning::before {
content: var(--icon-error-warning);
color: var(--warningHeading);
}

.content-inner blockquote :is(h3, h4).error {
.content-inner section.admonition > .admonition-title.error {
background-color: var(--errorHeadingBackground);
color: var(--errorHeading);
}
.content-inner blockquote :is(h3, h4).error::before {
.content-inner section.admonition > .admonition-title.error::before {
content: var(--icon-error-warning);
color: var(--errorHeading);
}

.content-inner blockquote :is(h3, h4).info {
.content-inner section.admonition > .admonition-title.info {
background-color: var(--infoHeadingBackground);
color: var(--infoHeading);
}
.content-inner blockquote :is(h3, h4).info::before {
.content-inner section.admonition > .admonition-title.info::before {
content: var(--icon-information);
color: var(--infoHeading);
}

.content-inner blockquote :is(h3, h4).neutral {
.content-inner section.admonition > .admonition-title.neutral {
background-color: var(--neutralHeadingBackground);
color: var(--neutralHeading);
}
.content-inner blockquote :is(h3, h4).neutral::before {
.content-inner section.admonition > .admonition-title.neutral::before {
content: var(--icon-double-quotes-l);
color: var(--neutralHeading);
}

.content-inner blockquote :is(h3, h4).tip {
.content-inner section.admonition > .admonition-title.tip {
background-color: var(--tipHeadingBackground);
color: var(--tipHeading);
}
.content-inner blockquote :is(h3, h4).tip::before {
.content-inner section.admonition > .admonition-title.tip::before {
content: var(--icon-information);
color: var(--tipHeading);
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
.content-inner section.admonition > .admonition-title code {
margin: 0 0.5ch;
}

.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) code {
.content-inner section.admonition code {
background-color: var(--admInlineCodeBackground);
border: 1px solid var(--admInlineCodeBorder);
color: var(--admInlineCodeColor);
}

.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) pre code {
.content-inner section.admonition pre code {
background-color: var(--admCodeBackground);
border: 1px solid var(--admCodeBorder);
color: var(--admCodeColor);
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) :is(a, a:visited) {
.content-inner section.admonition > .admonition-title :is(a, a:visited) {
color: inherit;
text-decoration-color: currentColor;
}

@media screen and (max-width: 768px) {
.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition {
margin-left: calc(-1 * var(--content-gutter));
margin-right: calc(-1 * var(--content-gutter));
padding-left: var(--content-gutter);
padding-right: var(--content-gutter);
border-radius: 0;
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition > .admonition-title {
margin: 0 calc(-1 * var(--content-gutter));
}
}
33 changes: 15 additions & 18 deletions assets/css/content/epub-admonition.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition {
border-left: solid 4px;
color: var(--black);
font-size: 0.9em;
Expand All @@ -9,68 +9,65 @@
page-break-inside: avoid;
}

.content-inner blockquote.warning {
.content-inner section.admonition.warning {
background-color: var(--warningBackground);
border-left-color: var(--warningHeadingBackground);
}

.content-inner blockquote.error {
.content-inner section.admonition.error {
background-color: var(--errorBackground);
border-left-color: var(--errorHeadingBackground);
}

.content-inner blockquote.info {
.content-inner section.admonition.info {
background-color: var(--infoBackground);
border-left-color: var(--infoHeadingBackground);
}

.content-inner blockquote.neutral {
.content-inner section.admonition.neutral {
background-color: var(--neutralBackground);
border-left-color: var(--neutralHeadingBackground);
}

.content-inner blockquote.tip {
.content-inner section.admonition.tip {
background-color: var(--tipBackground);
border-left-color: var(--tipHeadingBackground);
}

.content-inner blockquote :is(h3, h4) {
.content-inner section.admonition > .admonition-title {
font-weight: bold;
margin: 0px 10px 5px 0px;
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
font-style: normal;
font-weight: 700;
}

.content-inner blockquote :is(h3, h4).warning {
.content-inner section.admonition > .admonition-title.warning {
color: var(--warningHeadingBackground);
}
.content-inner blockquote :is(h3, h4).error {
.content-inner section.admonition > .admonition-title.error {
color: var(--errorHeadingBackground);
}
.content-inner blockquote :is(h3, h4).info {
.content-inner section.admonition > .admonition-title.info {
color: var(--infoHeadingBackground);
}
.content-inner blockquote :is(h3, h4).neutral {
.content-inner section.admonition > .admonition-title.neutral {
color: var(--neutralHeadingBackground);
}
.content-inner blockquote :is(h3, h4).tip {
.content-inner section.admonition > .admonition-title.tip {
color: var(--tipHeadingBackground);
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
.content-inner section.admonition > .admonition-title code {
margin: 0 0.5ch;
}

.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) code {
.content-inner section.admonition code {
background-color: var(--admInlineCodeBackground);
border: 1px solid var(--admInlineCodeBorder);
color: var(--admInlineCodeColor);
}

.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) pre code {
.content-inner section.admonition pre code {
background-color: var(--admCodeBackground);
border: 1px solid var(--admCodeBorder);
color: var(--admCodeColor);
Expand Down
4 changes: 2 additions & 2 deletions assets/css/content/general.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@
font-weight: normal;
}

.content-inner blockquote {
.content-inner blockquote, .content-inner section.admonition {
border-left: 3px solid var(--blockquoteBorder);
position: relative;
margin: 1.5625em 0;
Expand All @@ -106,7 +106,7 @@
background-color: var(--blockquoteBackground);
border-radius: var(--borderRadius);
}
.content-inner blockquote p:last-child {
.content-inner blockquote p:last-child, .content-inner section.admonition p:last-child {
padding-bottom: 1em;
margin-bottom: 0;
}
Expand Down
4 changes: 2 additions & 2 deletions assets/css/print.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,11 @@
display: none;
}

.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition {
border: 2px solid var(--gray400);
}

.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
.content-inner section.admonition > .admonition-title {
color: var(--textHeaders);
border-bottom: 2px solid var(--gray400);
}
Expand Down
3 changes: 2 additions & 1 deletion assets/css/tabset.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,8 @@
}

.tabset-panel pre,
.tabset-panel blockquote {
.tabset-panel blockquote,
.tabset-panel section.admonition {
margin-left: calc(-1 * var(--tabsetPadding)) !important;
margin-right: calc(-1 * var(--tabsetPadding)) !important;
}
Expand Down
42 changes: 42 additions & 0 deletions lib/ex_doc/markdown/earmark.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ defmodule ExDoc.Markdown.Earmark do

@behaviour ExDoc.Markdown

@admonition_classes ~w(warning error info tip neutral)

@impl true
def available? do
match?({:ok, _}, Application.ensure_all_started(:earmark_parser)) and
Expand Down Expand Up @@ -74,6 +76,46 @@ defmodule ExDoc.Markdown.Earmark do
"$$\n#{content}\n$$"
end

# Convert admonition blockquotes to sections for screen reader accessibility
defp fixup(
{"blockquote", blockquote_attrs, [{tag, h_attrs, h_content, h_meta} | rest] = ast,
blockquote_meta}
)
when tag in ["h3", "h4"] do
{h_classes, h_attrs} = Enum.split_with(h_attrs, &match?({"class", _}, &1))
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can also use List.keytake and similar. :) Similar below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I'm glad to hear that 😅
I think I can make it look better with keytake/keystore

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you take, you probably don't need keystore, you can just prepend it: [{"class", val} | attrs]


h_admonition =
with [{"class", classes}] <- h_classes,
class_list <- String.split(classes),
adm_classes = [_ | _] <- Enum.filter(class_list, &(&1 in @admonition_classes)) do
{Enum.join(adm_classes, " "), classes}
else
[] -> nil
end

blockquote_attrs_fn = fn admonition_classes ->
case Enum.split_with(blockquote_attrs, &match?({"class", _}, &1)) do
{[], attrs} ->
[{"class", admonition_classes}, {"role", "note"} | attrs]

{[{"class", classes}], attrs} ->
classes = String.trim_trailing(classes) <> " #{admonition_classes}"
[{"class", classes}, {"role", "note"} | attrs]
end
end

if h_admonition do
{h_admonition_classes, h_classes} = h_admonition
blockquote_attrs = blockquote_attrs_fn.("admonition #{h_admonition_classes}")
h_elem = {tag, [{"class", "admonition-title #{h_classes}"} | h_attrs], h_content, h_meta}

fixup({"section", blockquote_attrs, [h_elem | rest], blockquote_meta})
else
# regular blockquote, copied fixup/1 here to avoid infinite loop
{:blockquote, Enum.map(blockquote_attrs, &fixup_attr/1), fixup(ast), blockquote_meta}
end
end

defp fixup({tag, attrs, ast, meta}) when is_binary(tag) and is_list(attrs) and is_map(meta) do
{fixup_tag(tag), Enum.map(attrs, &fixup_attr/1), fixup(ast), meta}
end
Expand Down
41 changes: 41 additions & 0 deletions test/ex_doc/markdown/earmark_test.exs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,47 @@ defmodule ExDoc.Markdown.EarmarkTest do
]
end

test "converts blockquote admonitions to regular divs" do
info = """
> #### Info {: .info .ignore}
> This is info.
"""

assert Markdown.to_ast(info, []) == [
{:section, [class: "admonition info", role: "note"],
[
{:h4, [class: "admonition-title ignore info"], ["Info"], %{}},
{:p, [], ["This is info."], %{}}
], %{}}
]

not_admonition = """
> ### H3 {: .xyz}
> This is NOT an admonition!
"""

assert Markdown.to_ast(not_admonition, []) == [
{:blockquote, [],
[
{:h3, [class: "xyz"], ["H3"], %{}},
{:p, [], ["This is NOT an admonition!"], %{}}
], %{}}
]

warning_error = """
> ### Warning! Error! {: .warning .error}
> A warning and an error.
"""

assert Markdown.to_ast(warning_error, []) == [
{:section, [class: "admonition error warning", role: "note"],
[
{:h3, [class: "admonition-title error warning"], ["Warning! Error!"], %{}},
{:p, [], ["A warning and an error."], %{}}
], %{}}
]
end

test "keeps math syntax without interpreting math as markdown" do
assert Markdown.to_ast("Math $x *y* y$", []) == [
{:p, [], ["Math ", "$x *y* y$"], %{}}
Expand Down
Loading