Merge 0d8edaf into 8777f56

docs/using/syntax.md

@@ -61,7 +61,7 @@ For more information, also see the [CommonMark Spec](https://spec.commonmark.org
 - **ThematicBreak**: `---`
 - **List**: bullet points or enumerated.
 - **Table**: Standard markdown table styles.
-- **Footnote**: A substitution for an inline link (e.g. `[key][name]`), which can have a reference target (no spaces), and an optional title (in `"`), e.g. `[key]: https://www.google.com "a title"`
+- **LinkDefinition**: A substitution for an inline link (e.g. `[key][name]`), which can have a reference target (no spaces), and an optional title (in `"`), e.g. `[key]: https://www.google.com "a title"`
 - **Paragraph**: General inline text
 
 ### Span (Inline) Tokens
@@ -304,7 +304,7 @@ header-rows: 1
 
 For example, the following code:
 
-```
+```md
 Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`
 ```
 

myst_parser/block_tokens.py

@@ -25,7 +25,7 @@
     "BlockBreak",
     "List",
     "Table",
-    "Footnote",
+    "LinkDefinition",
     "FrontMatter",
     "Paragraph",
 ]
@@ -109,6 +109,16 @@ def __repr__(self):
         return "MyST.{}(blocks={})".format(self.__class__.__name__, len(self.children))
 
 
+class LinkDefinition(Footnote):
+    """This has been renamed since, these actually refer to
+    https://spec.commonmark.org/0.28/#link-reference-definitions,
+    rather than what would generally be considered a footnote:
+    https://www.markdownguide.org/extended-syntax/#footnotes
+    """
+
+    pass
+
+
 class LineComment(block_token.BlockToken):
     """Line comment start with % """
 

tests/test_commonmark/test_commonmark.py

@@ -6,7 +6,7 @@
 
 import pytest
 
-from mistletoe import Document
+from myst_parser.block_tokens import Document
 from myst_parser.html_renderer import HTMLRenderer
 
 with open(os.path.join(os.path.dirname(__file__), "commonmark.json"), "r") as fin:
@@ -15,6 +15,12 @@
 
 @pytest.mark.parametrize("entry", tests)
 def test_commonmark(entry):
+    if entry["example"] in [65, 67]:
+        # This is supported by numerous Markdown flavours, but not strictly CommonMark
+        # see: https://talk.commonmark.org/t/metadata-in-documents/721/86
+        pytest.skip(
+            "Thematic breaks on the first line conflict with front matter syntax"
+        )
     test_case = entry["markdown"].splitlines(keepends=True)
     with HTMLRenderer() as renderer:
         output = renderer.render(Document(test_case))

tests/test_renderers/test_docutils.py

@@ -279,7 +279,7 @@ def test_block_break(renderer_mock):
     )
 
 
-def test_footnote(renderer):
+def test_link_reference(renderer):
     renderer.render(
         Document(["[name][key]", "", '[key]: https://www.google.com "a title"', ""])
     )
@@ -293,6 +293,20 @@ def test_footnote(renderer):
     )
 
 
+def test_link_reference_no_key(renderer):
+    renderer.render(
+        Document(["[name]", "", '[name]: https://www.google.com "a title"', ""])
+    )
+    assert renderer.document.pformat() == dedent(
+        """\
+    <document source="notset">
+        <paragraph>
+            <reference refuri="https://www.google.com" title="a title">
+                name
+    """
+    )
+
+
 def test_block_quotes(renderer):
     renderer.render(
         Document(

tests/test_syntax/test_ast.py

@@ -125,3 +125,17 @@ def test_block_break(name, ast_renderer, data_regression, strings):
 def test_front_matter(name, ast_renderer, data_regression, strings):
     document = Document(strings)
     data_regression.check(ast_renderer.render(document))
+
+
+@pytest.mark.parametrize(
+    "name,strings",
+    [
+        ("ref_first", ["[ref]", "", '[ref]: https://google.com "title"']),
+        ("ref_last", ['[ref]: https://google.com "title"', "", "[ref]"]),
+        ("ref_syntax", ["[*syntax*]", "", '[*syntax*]: https://google.com "title"']),
+        ("ref_escape", ["[ref]", "", '\\[ref]: https://google.com "title"']),
+    ],
+)
+def test_link_references(name, strings, ast_renderer, data_regression):
+    document = Document(strings)
+    data_regression.check(ast_renderer.render(document))

tests/test_syntax/test_ast/test_link_references_ref_escape_strings3_.yml

@@ -0,0 +1,21 @@
+children:
+- children:
+  - content: '[ref]'
+    type: RawText
+  range:
+  - 1
+  - 1
+  type: Paragraph
+- children:
+  - children:
+    - content: '['
+      type: RawText
+    type: EscapeSequence
+  - content: 'ref]: https://google.com "title"'
+    type: RawText
+  range:
+  - 3
+  - 3
+  type: Paragraph
+footnotes: {}
+type: Document

tests/test_syntax/test_ast/test_link_references_ref_first_strings0_.yml

@@ -0,0 +1,17 @@
+children:
+- children:
+  - children:
+    - content: ref
+      type: RawText
+    target: https://google.com
+    title: title
+    type: Link
+  range:
+  - 1
+  - 1
+  type: Paragraph
+footnotes:
+  ref:
+  - https://google.com
+  - title
+type: Document

tests/test_syntax/test_ast/test_link_references_ref_last_strings1_.yml

@@ -0,0 +1,17 @@
+children:
+- children:
+  - children:
+    - content: ref
+      type: RawText
+    target: https://google.com
+    title: title
+    type: Link
+  range:
+  - 3
+  - 3
+  type: Paragraph
+footnotes:
+  ref:
+  - https://google.com
+  - title
+type: Document

tests/test_syntax/test_ast/test_link_references_ref_syntax_strings2_.yml

@@ -0,0 +1,19 @@
+children:
+- children:
+  - children:
+    - children:
+      - content: syntax
+        type: RawText
+      type: Emphasis
+    target: https://google.com
+    title: title
+    type: Link
+  range:
+  - 1
+  - 1
+  type: Paragraph
+footnotes:
+  '*syntax*':
+  - https://google.com
+  - title
+type: Document