diff --git a/.github/media/callout-details.png b/.github/media/callout-details.png new file mode 100644 index 0000000000..7d0e922a6c Binary files /dev/null and b/.github/media/callout-details.png differ diff --git a/.github/media/callouts.png b/.github/media/callouts.png index f55e318b06..177bf7e4be 100644 Binary files a/.github/media/callouts.png and b/.github/media/callouts.png differ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 398002e105..d04de6aa17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -468,7 +468,7 @@ A callout draws attention to something learners should slow down and read. > [!NOTE] > Callouts can be distracting when people are quickly skimming a page. So only use them if the information absolutely should not be missed! -Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). To add a callout, use a special blockquote line specifying the callout type, followed by the callout information in a standard blockquote. Five types of callouts are available: +Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). To add a callout, use a special blockquote line specifying the callout type, followed by the callout information in a standard blockquote. The following types of callouts are available: ```mdx > [!NOTE] @@ -485,11 +485,34 @@ Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/ > [!CAUTION] > Advises about risks or negative outcomes of certain actions. + +> [!QUIZ] +> An opportunity for users to check their understanding. ``` The image below shows what this example looks like once rendered. -![An example of each callout type: NOTE, TIP, IMPORTANT, WARNING, CAUTION](/.github/media/callouts.png) +![An example of each callout type: NOTE, TIP, IMPORTANT, WARNING, CAUTION, QUIZ](/.github/media/callouts.png) + +You can optionally specify an `id` attribute for a callout which allows for direct linking, e.g. `/docs/example#useful-info`: + +```mdx +> [!NOTE useful-info] +> Useful information that users should know, even when skimming content. +``` + +You can create a collapsible section within a callout by using a thematic break (`---`). Content following the break is hidden by default and can be toggled by the user: + +```mdx +> [!QUIZ] +> Why does handshake do a redirect? Why can’t it make a fetch request to FAPI and get a new token back that way? Not needing to redirect would be a better user experience. +> +> --- +> +> Occaecati esse ut iure in quam praesentium nesciunt nemo. Repellat aperiam eaque quia. Aperiam voluptatem consequuntur numquam tenetur. Quibusdam repellat modi qui dolor ducimus ut neque adipisci dolorem. Voluptates dolores nisi est fuga. +``` + +![An example of a collapsible section inside a quiz callout](/.github/media/callout-details.png) ### `` diff --git a/prettier-mdx.mjs b/prettier-mdx.mjs index 56323fe592..664f277b08 100644 --- a/prettier-mdx.mjs +++ b/prettier-mdx.mjs @@ -192,8 +192,8 @@ function remarkAddCalloutMarkers() { visit(tree, 'blockquote', (node) => { if (node.children[0]?.type === 'paragraph' && node.children[0].children[0]?.type === 'text') { node.children[0].children[0].value = node.children[0].children[0].value.replace( - /^\[\s*!\s*([A-Z]+)\s*\]/, - '__CALLOUT_MARKER__!$1]', + /^\[\s*!\s*([A-Z]+)(\s+[0-9a-z-]+)?\s*\]/, + (_, type, id) => `__CALLOUT_MARKER__!${type}${id ? ` ${id.trim()}` : ''}]`, ) } })