Markdown Specifics

This is where the markdown content goes for the article that are writing. Please use standard Markdown. It should go in the appropriate folder.

Note

The h1 will be generated for you from the title metadata above. Please delete the h1 when you transfer it over.

Markdown Additions

Markdown is good for putting out basic HTML, but it’s lacking a few features. The following is an overview of some of the additions to markdown that have been configured.

Links

When you link to another document, you can do this in one of two ways:

• Use the full ta11y-1 link: https://www.ta11y.org/learning/topic?key=test_tool.comprehensive_wave
• Use a shortened path the article, with a docs protocol and no locale: learning://digital-testing/test-tools/wave.
  • This one is preferred, but not required.

When you link to an external site, the platform will automatically add an external icon indicating that the link is external. For example, a link to Google that has the indicator.

Code

You can add specific syntax highlighting by specifying the language after the backticks (```). So instead of a “black and white” stand code block:

<table>
    <caption class="example"></caption>
  <tr>
      <th></th>
      <th style="text-align: center"></th>
  </tr>
  <tr>
      <td></td>
      <td></td>
  </tr>
</table>

You can colorize it by adding the language (html in this case):

Markdown example with language

```html
  <table>
    ...
  </table>
```

Which will give it some syntax coloring, making it easier to read:

<table>
  <caption class="example"></caption>
  <tr>
      <th></th>
      <th style="text-align: center"></th>
  </tr>
  <tr>
      <td></td>
      <td></td>
  </tr>
</table>

The code with syntax coloring

A title can be added as well:

Markdown example with a title

```html title="Code Example: Basic Data Table"
  <table>
  ...
  </table>
```

which you can see here:

Code Example: Basic Data Table

<table>
  ...
</table>

More examples and useful features can be found on Expressive Code’s documentation site.

Asides

Sometimes you need to have a callout to specifically grab attention to a point. There are three asides that are available:

Markdown examples of Asides

:::note[Title goes between the brackets]
A standard callout with a blue background and an information icon.
:::

:::caution[Title goes between the brackets]
A callout with a yellow background and an warning road sign icon.
:::

:::danger[Title goes between the brackets]
A callout with a pink background and a stop sign icon, signalling that callout can have dangerous implications.
:::

Title goes between the brackets

A standard callout with a blue background and an information icon.

Title goes between the brackets

A callout with a yellow background and an warning road sign icon.

Title goes between the brackets

A callout with a pink background and a stop sign icon, signalling that callout can have dangerous implications.

Rendered aside examples

As you can see in the example above, the title is surrounded by square brackets right afterwards ([]). If you don’t include a title, it will default to the name of the Aside (Note, Caution and Danger).

Note

In MDX, you may use the Asides component to do the same thing.

Figures

Figures are not available in basic Markdown, so we’ve added an extension to be able to create them. Just like the titles in Asides, the caption is surrounded by square brackets right afterwards ([]). If you don’t include a caption, none will be rendered.

Markdown example of a figure

:::figure[Caption goes between the brackets]
  ...
  Standard markdown can go in the middle
  ...
:::

So if you wrote the following:

Markdown of the example below

:::figure[Have to have a cute picture of a dog as an example]
![A couple of adorable brown puppies](https://images.rawpixel.com/image_social_landscape/cHJpdmF0ZS9sci9pbWFnZXMvd2Vic2l0ZS8yMDIyLTA1L25zODIzMC1pbWFnZS5qcGc.jpg)
:::

You would get this as a result:

Have to have a cute picture of a dog as an example

Optional Attributes

You can also add an id and a class attribute to figures. For instance, use the bordered class to add some additional vertical separation.

Markdown example of a figure with a class and id

:::figure[A figure with a border]{class="bordered" id="figure1"}
   * Any old markdown
   * can be placed
   * inside a `figure`.
:::

To get to [figure 1](#figure1), click that link.

• Any old markdown
• can be placed
• inside a figure.

A figure with a border

To get to figure 1, click that link.

MDX Issues

For MDX, to add the id or class attribute, you will either need to use raw HTML or use the Figure or (ImageFigure) component to do the same thing.

To use the Figure component:

​
import Figure from "@components/Figure.astro";


<Figure id="figure1" class="border" caption="A figure with a border">
  ...
</Figure>

Tables

When writing a table, it is impossible to write a caption in standard Markdown. So, we’ve added a method similar to figures to provide a caption for a table.

Markdown example of a table with a caption

:::table[Caption goes between the brackets]
  | Column Left | Column Centered | Column Right |
  |----------|:--------:|---------:|
  | Cell 1A  | Cell 1B  | Cell 1C  |
  | Cell 2A  | Cell 2B  | Cell 2C  |
:::

Example using code above:

Column Left	Column Centered	Column Right
Cell 1A	Cell 1B	Cell 1C
Cell 2A	Cell 2B	Cell 2C

Caption goes between the brackets

Optional Attributes

Just like a figure, you can add an id and a class to a table. For example, when writing a table, you may want to show each of the cells individually. When this happens, add a class="cell-outline" to specifically show a border on each cell.

So, if you write the following:

Markdown example of a table with class and id

:::table[Caption goes between the brackets]{class="cell-outline" id="table1"}
  | Column Left | Column Centered | Column Right |
  |----------|:--------:|---------:|
  | Cell 1A  | Cell 1B  | Cell 1C  |
  | Cell 2A  | Cell 2B  | Cell 2C  |
:::

With [a link to that table](#table1) rendered correctly.

Example using code above:

Column Left	Column Centered	Column Right
Cell 1A	Cell 1B	Cell 1C
Cell 2A	Cell 2B	Cell 2C

Caption goes between the brackets

With a link to that table rendered correctly.

Caution

You can’t add an id or a class in MDX. You’ll have to write out the table (or we’ll have to add a component).

Steps

When writing an ordered list (ol), sometimes most of the list items have a lot of content in a single item. When this happens, you can add the following block:

Markdown for a steps block with an ordered list

:::steps
1. Larger and Fancier
2. List Items, than can

   hold **additional** paragraphs, figures or tables.
3. ...
:::

Example using code above:

1. Larger and Fancier

2. List Items, than can

   hold additional paragraphs, figures or tables.

3. …

An example of steps

You can also add an id, just like on figures or tables.

Note

In MDX, you may use the Steps component to do the same thing.

Definition Lists

If you have a list or table that is really just providing a set of definitions, you should consider using a definition list instead. To do this, create a new paragraph with the term, and prepend the definition with a colon (:).

So, if you write this:

Code for a definition list

Term A
: This is the definition for term A.

Term B
: This is the definition for term B.
: Each term can have multiple definitions
   * As well as additional markdown within a definition by indenting it.
   * Just like this.

It will render as this:

Term A

This is the definition for term A.

Term B

This is the definition for term B.

Each term can have multiple definitions:

• As well as additional markdown within a definition by indenting it.
• Just like this.

An example of a definition list

Footnotes (Citations)

Footnotes can be added to each page rather simply:

Some example footnotes in Markdown

Here is a simple footnote[^1].
* Some example text.
* Another reference to the first footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: References can contain [links](https://www.ta11y.org) and other formatting.
[^2]: To add line breaks within a footnote, add a `\` to the end of a line.\
This is a second line.

They will look like the following in the flow of the document:

Here is a simple footnote¹.

• Some example text.
• Another reference to the first footnote¹.

A footnote can also have multiple lines².

These footnotes will show up at the bottom of this page.

Example of Foonotes

This will produce a Footnotes section at the bottom of the page, with the appropriate references.

For more information, please see the Starlight Documentation on Footnotes.

Hiding back references

Each footnote will automatically create a backreference link for the reader to be able to resume where they were. However, if you use multiple references to the same footnote, this will become overwhelming and not useful. To hide the backreferences, insert the following in your markdown file:

<style>a[data-footnote-backref] { display: none }</style>

Metadata (Frontmatter)

The reference for the metadata (or frontmatter) at the top of each document is found on the Starlight Documentation page. However, there are some additions that will be useful to know as well as some specific mentions.

Contributors

Please list any contributors in the metadata section. Make sure they have a representative file in the /astro/src/content/team folder.

Example of contributors

---
title: An article
...
contributors:
  - en/ellen-liebert
  - en/jonathan-katz-ouziel
  - en/rachael-bradley-montgomery
---

Topic keys

Please list any topic keys that an article has in the previous version of ta11y. The topic key is the part after key= in the URL for any ta11y article. Since some articles have moved around, this is technically a list.

Example of topicKeys

---
title: Use Positive Language
...
topicKeys:
  - writing.lang_positive
  - writing.positive
---

From the ‘Positive Langugage’ article, which has multiple keys

Sidebar

The sidebar section determines the label, order and any badge that appears in the sidebar (or the main table of contents). The order shouled match the order of the article in its category. The label is really useful when the article title is long or contains redundant information with its category.

Example with sidebar

---
title: Page with a custom sidebar
...
sidebar:
  label: Page with sidebar
  order: 3
  badge: New
---

For more details, please see the Starlight Documentation on Sidebar Configuration.

Article Status

Draft

If you add a draft: true to the metadata, the article will be available in development mode, but it won’t be published. This is useful when you’ve got an article in progress, but haven’t figured out how to fully convert all of the information.

Example with article in draft mode

---
title: Page with a draft status
...
draft: true
---

Stub

If you add a stub: true to the metadata, the article will be published, but with a note at the top indicating the article is just a stub article. This is useful when you’ve got an article with just a summary and nothing else.

Example with a stub article

---
title: Page with an stub status
...
stub: true
---

Incomplete

If you add a incomplete: true to the metadata, the article will be published, but with a note at the top indicating the article is not finished. This is useful when you’ve got an article with some sections fully complete and others empty.

Example with an incomplete article

---
title: Page with an incomplete status
...
incomplete: true
---

Last Updated

To help keep track of when an article is updated, add a lastUpdated tag with date formatted as YYYY-MM-DD. This will print out a note when the article was written.

Example with a date

---
title: Page with a last updated date
...
lastUpdated: 2026-02-01
---

Footnotes

1. References can contain links and other formatting. ↩ ↩²

2. To add line breaks within a footnote, add a \ to the end of a line.
   This is a second line. ↩