✨ New table of contents directive

[fwkoch]

This PR addresses #1800

It introduces a new toc directive that, for site builds, is transformed into a list-based table of contents. You may specify context to switch between project, page, and section contents. The default context is project.

• project - for this context, entries in the table of contents are all project pages and folders. You may also use toctree as an alias for the directive. (This provides partial functionality similar to the sphinx toctree directive, although that directive allows you to define child pages and their order. The MyST toc directive is only for display and entirely dependent on the toc structure defined in the myst.yml file. See sphinx toctree here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree)

  The following are all equivalent

  ```{toc}
  ```
  
  ```{tableofcontents}
  :context: project
  ```
  
  ```{toctree}
  ```
  

• page - for this context, entries in the table of contents are all the headings on a page.

  ```{toc}
  :context: page
  ```
  

• section - for this context, entries in the table of contents are only the headings of the current section you are in (sections are delimited by headings of the same depth). You may also use contents as an alias for toc directive with section context, to provide functionality similar to the docutils contents directive: https://docutils.sourceforge.io/0.4/docs/ref/rst/directives.html#table-of-contents)

  The following are all equivalent

  ```{toc}
  :context: section
  ```
  
  ```{contents}
  ```
  

You may also provide a heading for your table of contents:

```{toc} My Contents
```

Currently toc directives are ignored by PDF and other non-site build targets.

[changeset-bot]

🦋 Changeset detected

Latest commit: aa26dd9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
myst-directives	Patch
myst-transforms	Patch
myst-cli	Patch
myst-parser	Patch
myst-roles	Patch
myst-to-html	Patch
mystmd	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR