📚 DOCS: Full update

CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 0.19.0 - 2023-03-01
+
+This release brings a number of exciting new features, improvements, and upgrades 🎉
+
+Full Changelog: [v0.18.1...v0.19.0](https://github.com/executablebooks/MyST-Parser/compare/v0.18.1...v0.19.0)
+
+### 📚 Rewritten documentation
+
+The documentation has been almost completely rewritten,
+with a clearer structure, many more examples, rich hover tips, and a new live preview page ⚡️ (powered by [pyscript](https://pyscript.readthedocs.io/), <gh-pr:717>).
+
+The code base API is also now fully documented by [sphinx-autodoc2](https://sphinx-autodoc2.readthedocs.io/), which even allows for MyST docstrings! (<gh-pr:704>).
+
+### ⬆️ Add Sphinx 6 support, drop Sphinx 4
+
+The code base has been updated to support sphinx v6, and is no longer tested against sphinx v4 (<gh-pr:664>)
+
+### 📄 Extended docutils (single-page) support
+
+The `docutils` parser now supports many more features, and improvements to support live previews:
+
+- `myst_suppress_warnings` option added, mirroring Sphinx, to suppress MyST warnings (<gh-pr:655>)
+- `myst_meta_html` and `myst_substitutions` options are now supported (<gh-pr:672>)
+- `myst_heading_anchors` option is now supported (<gh-pr:678>)
+- Math block labels syntax is now supported (<gh-pr:668>)
+- Missing directive/role errors errors are now suppressable warnings (<gh-pr:687>)
+- Non-fatal directive parsing errors are now suppressable warnings (<gh-pr:682>)
+- Most of the extended markdown syntax below is also supported
+
+### 🔗 Extended Markdown links
+
+See the [Extended Markdown links](docs/syntax/cross-referencing.md) section for the full guide.
+
+You can now use standard Markdown link syntax to reference many different types of targets, in a more consistent way.
+
+- `[text](relative/path/myfile.md)` work as previously, to link to files,
+  but they can also be relative to source directory: `[text](/path/from/srcdir/myfile.md)`.
+  You can also use `<project:file.md>`
+- `<path:myfile.txt>` will link specifically to a downloadable file
+- `[text](#target)` or `<project:#target>` will link (in order of priority) to any local target, local heading anchor, target in the same project, or intersphinx (inventory) target
+- `[text](inv:name:domain:type#target)` will link specifically to a Sphinx inventory target, or to any inventory `<inv:#target>`, and can even use `*` wildcards like `<inv:*:*:*#*.target>`
+  - This can even be used in docutils, with the new `myst_inventories` config option
+  - The `myst-inv` CLI makes it easy to find the correct inventory target
+
+:::{tip}
+It is advised (although not immediately necessary) to prefix all internal references with `#`.
+For example, `[...](my-reference)`, should be changed to `[...](#my-reference)`.
+:::
+
+### `{}` Attributes syntax
+
+The [`attrs_inline` and `attrs_block`](docs/syntax/optional.md#attributes) extensions allow for common Markdown syntaxes to be extended with greater control over the output.
+
+For example, you can now add classes, ids, and other attributes to inline code, images, and links, as well as to code blocks and directives.
+
+- Inline code: `` `a = 1`{#id .class l=python} ``
+- Images: `![image](image.png){#id .class width=100px}`
+- Text spans: `[some text]{#id .class}`
+
+A paragraph block can have attributes too:
+
+```markdown
+{#id .class}
+This is a paragraph with an id and class
+```
+
+A code fence can be given line numbers and line emphasis:
+
+````markdown
+{#id .class lineno-start=1 emphasize-lines="2,3"}
+```python
+a = 1
+b = 2
+c = 3
+```
+````
+
+A definition list can be turned into a glossary, with referenceable terms:
+
+```markdown
+{.glossary}
+term name
+: Definition of the term
+```
+
+Quote blocks can be given an attribution:
+
+```markdown
+{attribution="Chris Sewell"}
+> My quote
+```
+
+### 👌 Miscellaneous improvements
+
+- Nested headings (e.g. inside directives) are now allowed in MyST and are correctly rendered in HTML (<gh-pr:711>)
+- The `colon_fence` extension now renders internal content as MyST, rather than as a code block (<gh-pr:713>)
+- The `include` directive in MyST documents now supports a `:heading-offset:` option, to offset the heading levels in the included document
+- The `myst_heading_slug_func` option now supports setting a `str` which points to a fully qualified function name, e.g. `"module.path.func"` (<gh-pr:696>)
+- The `myst_enable_checkboxes` option allows for task list checkboxes to be enabled/disabled (<gh-pr:686>)
+
+### Additional contributions
+
+- 🐛 FIX: Remove unnecessary assert in <gh-pr:659>, thanks to <gh-user:n-peugnet>
+- 🔧 ci(deps): setup dependabot (<gh-pr:669>), thanks to <gh-user:mmorel-35>
+- 🔧: Depend on typing_extensions only on `Python<3.8` in <gh-pr:642>, thanks to <gh-user:hukkin>
+
 ## 0.18.1 - 2022-27-09
 
 Full Changelog: [v0.18.0...v0.18.1](https://github.com/executablebooks/MyST-Parser/compare/v0.18.0...v0.18.1)
@@ -16,7 +122,7 @@ Full Changelog: [v0.17.2...v0.18.0](https://github.com/executablebooks/MyST-Pars
 
 This release adds support for Sphinx v5 (dropping v3), restructures the code base into modules, and also restructures the documentation, to make it easier for developers/users to follow.
 
-It also introduces **document-level configuration**  *via* the Markdown top-matter, under the `myst` key.
+It also introduces **document-level configuration**  *via* the Markdown front-matter, under the `myst` key.
 See the [Local configuration](docs/configuration.md) section for more information.
 
 ### Breaking changes
@@ -28,7 +134,7 @@ The `to_docutils`, `to_html`, `to_tokens` (from `myst_parser/main.py`) and `mock
 Instead, for single page builds, users should use the docutils parser API/CLI (see [](docs/docutils.md)),
 and for testing, functionality has been moved to <https://github.com/chrisjsewell/sphinx-pytest>.
 
-The top-level `html_meta` and `substitutions` top-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the `myst` config, e.g.
+The top-level `html_meta` and `substitutions` front-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the `myst` config, e.g.
 
 ```yaml
 ---
@@ -100,7 +206,7 @@ In addition, configuration to more finely tune this behaviour has been added.
 - `myst_url_schemes=("http", "https")`, sets what URL schemes are treated as (1)
 - `myst_ref_domains=("std", "py")`, sets what Sphinx reference domains are checked, when handling (3)
 
-See [Markdown Links and Referencing](docs/syntax/syntax.md#markdown-links-and-referencing) for more information.
+See [Markdown Links and Referencing](docs/syntax/cross-referencing.md) for more information.
 
 ### ‼️ Dollarmath is now disabled by default
 
@@ -143,7 +249,7 @@ would be equivalent to:
 # My Title with *emphasis*
 ```
 
-See [Front matter](docs/syntax/syntax.md#front-matter) for more information.
+See [Front matter](docs/configuration.md) for more information.
 
 ### 👌 Internal improvements
 
@@ -291,7 +397,7 @@ is converted to:
 
 These classes should be supported by most sphinx HTML themes.
 
-See [Tables syntax](docs/syntax/syntax.md#tables) for more information.
+See [Tables syntax](docs/syntax/tables.md) for more information.
 
 ### Pull Requests
 
@@ -382,7 +488,7 @@ In particular for users, this update alters the parsing of tables to be consiste
   > {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
   ```
 
-  See [the roles syntax guide](docs/syntax/syntax.md) for further information.
+  See [the roles syntax guide](docs/syntax/roles-and-directives.md) for further information.
 
 - The **`dmath_double_inline`** configuration option allows display math (i.e. `$$`) within an inline context.
   See [the math syntax guide](docs/syntax/optional.md#math-shortcuts) for further information.
@@ -467,7 +573,7 @@ Minor fixes:
 : If the label is an integer, then it will always use this integer for the rendered label (i.e. they are manually numbered).
 : Add `myst_footnote_transition` configuration, to turn on/off transition line.
 : Add `footnotes` class to transition `<hr>` in HTML.
-: See [the syntax guide](docs/syntax/syntax.md) for further information.
+: See [the typography guide](docs/syntax/typography.md) for further information.
 
 👌 IMPROVE: `substitution` extension logic
 

docs/_static/local.css

@@ -1,25 +1,13 @@
+/** landing page logo **/
+#landing-page-logo {
+    background: none;
+}
+
 /** Add a counter before subsections **/
-h1 {
+h1:not(.rubric) {
     counter-reset: subsection;
     text-decoration: underline;
 }
-h2 {
-    counter-reset: subsubsection;
-}
-h2::before {
-    counter-increment: subsection;
-    content: counter(subsection) ". ";
-}
-.tippy-box h2::before {
-    content: unset;
-}
-h3::before {
-    counter-increment: subsubsection;
-    content: counter(subsection) "." counter(subsubsection) ". ";
-}
-.tippy-box h3::before {
-    content: unset;
-}
 
 /** MyST examples */
 .myst-example {
@@ -35,30 +23,43 @@ h3::before {
 .myst-example-render {
     padding: 0.5rem;
 }
+.myst-example-render > :first-child {
+    margin-top: 0.5rem;
+}
 
 /** No icon for admonitions with no-icon class */
-.admonition > .admonition-title, div.admonition.no-icon > .admonition-title::before {
+div.admonition.no-icon > .admonition-title::before {
     content: "";
 }
-.admonition > .admonition-title, div.admonition.no-icon > .admonition-title {
+div.admonition.no-icon > .admonition-title {
     padding-left: .6rem;
 }
 
 /* Live preview page */
-iframe.pyscript, textarea.pyscript {
-    width: 100%;
-    height: 400px;
-}
-iframe.pyscript {
-    padding: 4px;
+@media (min-width: 768px) {
+    .preview-input-tabs {
+        height: 100%;
+    }
+    textarea.pyscript.input {
+        height: 100%;
+    }
 }
 textarea.pyscript {
+    width: 100%;
+    min-height: 300px;
     padding: 30px 20px 20px;
     border-radius: 8px;
     resize: vertical;
     font-size: 16px;
     font-family: monospace;
 }
+textarea.pyscript.output {
+    height: 100%;
+}
+div.pyscript {
+    min-height: 300px;
+}
+
 .display-flex {
     display: flex;
 }