From 4ad6e66e94560055ef0c88ffd448895607ae601e Mon Sep 17 00:00:00 2001
From: Anne Gentle <annegentle@justwriteclick.com>
Date: Thu, 4 Apr 2019 08:34:14 -0500
Subject: [PATCH 1/5] Clarify the specifics of Auto Toc Tree

Removes a double-up-on-the-verb situation.
---
 docs/auto_structify.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/auto_structify.md b/docs/auto_structify.md
index 676a028..a428bd3 100644
--- a/docs/auto_structify.md
+++ b/docs/auto_structify.md
@@ -38,13 +38,13 @@ One of important command in tools like sphinx is `toctree`. This is a command to
 tell sphinx about the structure of the documents. In markdown, usually we manually list of contents by a bullet list
 of url reference to the other documents.
 
-AutoStructify will transforms bullet list of document URLs
+AutoStructify transforms bullet list of document URLs like this
 
 ```
 * [Title1](doc1.md)
 * [Title2](doc2.md)
 ```
-will be translated to the AST of following reStructuredText code
+to the AST of this following reStructuredText code
 ```rst
 .. toctree::
    :maxdepth: 1

From 059e95d6f3968c8895646c5363e5a531a1d32f6a Mon Sep 17 00:00:00 2001
From: Daniel Andersson <dandersson@users.noreply.github.com>
Date: Sat, 6 Apr 2019 12:56:27 +0200
Subject: [PATCH 2/5] Use image description text as "alt", drop title

The current RecommonMark specification on images [0] says that:

    ![foo](/url "title")

should render as

    <p><img src="/url" alt="foo" title="title" /></p>

which means that "foo" should be the `alt` attribute, and "title" should
be the `title` attribute.

Currently, `recommonmark` will:

1. set the `alt` attribute to "title"
2. render "foo" as literal text following the image element.

Neither yields results in line with the RecommonMark standard, resulting
in the following when transformed to HTML:

    <p><img src="/url" alt="title" />foo</p>

While it might be surprising that `alt` is set to "title", the more
pressing issue is how the alt text becomes literal text within the
paragraph, typically not rendering well.

This commit instead makes `recommonmark`:

1. set the `alt` attribute to "foo"
2. drop "title" altogether since the `title` attribute is not supported
   in Docutils [1].

1 coincides with the specification, and 2 is in my mind the least
surprising solution within the capabilities of Docutils. The HTML will
now be:

    <p><img src="/url" alt="foo" /></p>

only differing in the missing `title` attribute when compared to the
specification.

[0]: https://spec.commonmark.org/0.28/#images
[1]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
---
 recommonmark/parser.py | 5 +++--
 tests/test_basic.py    | 2 +-
 tests/test_sphinx.py   | 2 +-
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/recommonmark/parser.py b/recommonmark/parser.py
index 857aded..e2f4ee9 100644
--- a/recommonmark/parser.py
+++ b/recommonmark/parser.py
@@ -178,8 +178,9 @@ class CommonMarkParser(parsers.Parser):
         img_node = nodes.image()
         img_node['uri'] = mdnode.destination
 
-        if mdnode.title:
-            img_node['alt'] = mdnode.title
+        if mdnode.first_child and mdnode.first_child.literal:
+            img_node['alt'] = mdnode.first_child.literal
+            mdnode.first_child.literal = ''
 
         self.current_node.append(img_node)
         self.current_node = img_node
diff --git a/tests/test_basic.py b/tests/test_basic.py
index 545c097..31860c4 100644
--- a/tests/test_basic.py
+++ b/tests/test_basic.py
@@ -232,7 +232,7 @@ class TestParsing(unittest.TestCase):
             <?xml version="1.0" ?>
             <document source="&lt;string&gt;">
               <paragraph>
-                <image alt="title" uri="/url">foo</image>
+                <image alt="foo" uri="/url"></image>
               </paragraph>
             </document>
             """
diff --git a/tests/test_sphinx.py b/tests/test_sphinx.py
index 00e2e03..feb4fe7 100644
--- a/tests/test_sphinx.py
+++ b/tests/test_sphinx.py
@@ -129,7 +129,7 @@ class GenericTests(SphinxIntegrationTests):
     def test_image(self):
         output = self.read_file('index.html')
         self.assertIn(
-            '<p><img alt="Example" src="image.png" />foo</p>',
+            '<p><img alt="foo" src="image.png" /></p>',
             output
         )
 

From 816fc608e65186b0896a1bffca3cfa425e33403a Mon Sep 17 00:00:00 2001
From: Daniel Andersson <dandersson@users.noreply.github.com>
Date: Sun, 7 Apr 2019 00:16:58 +0200
Subject: [PATCH 3/5] Add test cases for quotes in alt texts

---
 tests/sphinx_generic/index.md | 2 +-
 tests/test_basic.py           | 4 ++--
 tests/test_sphinx.py          | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/tests/sphinx_generic/index.md b/tests/sphinx_generic/index.md
index 64f21f9..d699b79 100644
--- a/tests/sphinx_generic/index.md
+++ b/tests/sphinx_generic/index.md
@@ -23,7 +23,7 @@ Foo
 
 Bar
 
-![foo](/image.png "Example")
+![foo "handle quotes"](/image.png "Example")
 
     #!/bin/sh
     python
diff --git a/tests/test_basic.py b/tests/test_basic.py
index 31860c4..798c395 100644
--- a/tests/test_basic.py
+++ b/tests/test_basic.py
@@ -226,13 +226,13 @@ class TestParsing(unittest.TestCase):
     def test_image(self):
         self.assertParses(
             """
-            ![foo](/url "title")
+            ![foo "handle quotes"](/url "title")
             """,
             """
             <?xml version="1.0" ?>
             <document source="&lt;string&gt;">
               <paragraph>
-                <image alt="foo" uri="/url"></image>
+                <image alt="foo &quot;handle quotes&quot;" uri="/url"></image>
               </paragraph>
             </document>
             """
diff --git a/tests/test_sphinx.py b/tests/test_sphinx.py
index feb4fe7..06078b1 100644
--- a/tests/test_sphinx.py
+++ b/tests/test_sphinx.py
@@ -129,7 +129,7 @@ class GenericTests(SphinxIntegrationTests):
     def test_image(self):
         output = self.read_file('index.html')
         self.assertIn(
-            '<p><img alt="foo" src="image.png" /></p>',
+            '<p><img alt="foo &quot;handle quotes&quot;" src="image.png" /></p>',
             output
         )
 

From 6e1f4abba0e96ab5728a81050992277f561838cb Mon Sep 17 00:00:00 2001
From: Daniel Andersson <dandersson@users.noreply.github.com>
Date: Sun, 7 Apr 2019 00:17:16 +0200
Subject: [PATCH 4/5] Handle quotes in alt texts

A bit of a brute force solution, but the parser splits the attribute
upon encountering a quote into multiple nodes. Walk through them,
collect strings and drop them from further parsing.
---
 recommonmark/parser.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/recommonmark/parser.py b/recommonmark/parser.py
index e2f4ee9..0046ea6 100644
--- a/recommonmark/parser.py
+++ b/recommonmark/parser.py
@@ -179,8 +179,14 @@ class CommonMarkParser(parsers.Parser):
         img_node['uri'] = mdnode.destination
 
         if mdnode.first_child and mdnode.first_child.literal:
-            img_node['alt'] = mdnode.first_child.literal
+            content = [mdnode.first_child.literal]
+            n = mdnode.first_child
             mdnode.first_child.literal = ''
+            mdnode.first_child = mdnode.last_child = None
+            while getattr(n, 'nxt'):
+                n.nxt, n = None, n.nxt
+                content.append(n.literal)
+            img_node['alt'] = ''.join(content)
 
         self.current_node.append(img_node)
         self.current_node = img_node

From ec0ada952def1700e2582ad43c7135e63f2aaa8f Mon Sep 17 00:00:00 2001
From: Gibson Fahnestock <gibfahn@gmail.com>
Date: Fri, 17 May 2019 16:34:18 +0100
Subject: [PATCH 5/5] Remove URL quoting from refs before passing to Sphinx

Sphinx allows refs with spaces etc, and in fact autogenerates them with
the command [`autosectionlabel`][].

So if you put a:

```markdown
[Link 1](<some ref>)
[Link 2](<https://foo.com/bar baz>)
```

Then the links will be `some%20ref` and `https://foo.com/bar%20baz`.

We want to keep the URL quoting for external references, but if we're
passing it as `:any:` to Sphinx we need to unquote so Sphinx can find
the correct reference, the `<some ref>` should map to:

```rst
:ref:`some ref`
```

[`autosectionlabel`](https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html)

Fixes: https://github.com/rtfd/recommonmark/issues/155
---
 README.md                  | 36 ++++++++++++++++++++++++++++++++++++
 recommonmark/parser.py     |  6 +++---
 tests/sphinx_xref/conf.py  |  3 +++
 tests/sphinx_xref/index.md |  4 ++++
 tests/sphinx_xref/link.md  |  4 ++++
 5 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 67feab2..e1e4214 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,41 @@ This allows you to write both `.md` and `.rst` files inside of the same project.
 
 For all links in commonmark that aren't explicit URLs, they are treated as cross references with the [`:any:`](http://www.sphinx-doc.org/en/stable/markup/inline.html#role-any) role. This allows referencing a lot of things including files, labels, and even objects in the loaded domain.
 
+#### Linking to headings in other files
+
+For linking to headings in other files you can use the [`autosectionlabel`][] sphinx feature, e.g.
+
+```python
+# conf.py
+
+extensions = [
+    # Auto-generate section labels.
+    'sphinx.ext.autosectionlabel',
+]
+
+# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
+# rather than 'path/to/file:heading'
+autosectionlabel_prefix_document = True
+```
+
+You would use it like:
+
+```markdown
+<!-- path/to/file_1.md -->
+
+# Title
+
+## My Subtitle
+```
+
+```markdown
+<!-- file_2.md -->
+
+[My Subtitle][]
+
+[My Subtitle]: <path/to/file_1:My Subtitle>
+```
+
 ### AutoStructify
 
 AutoStructify makes it possible to write your documentation in Markdown, and automatically convert this
@@ -118,3 +153,4 @@ and is now maintained in the Read the Docs (rtfd) GitHub organization.
 [dc]: http://docutils.sourceforge.net/docs/ref/doctree.html
 [sphinx-issue]: https://bitbucket.org/birkenfeld/sphinx/issue/825/markdown-capable-sphinx
 [so-question]: http://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst
+[`autosectionlabel`]: https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
diff --git a/recommonmark/parser.py b/recommonmark/parser.py
index 857aded..89b2b6c 100644
--- a/recommonmark/parser.py
+++ b/recommonmark/parser.py
@@ -11,9 +11,9 @@ from commonmark import Parser
 from warnings import warn
 
 if sys.version_info < (3, 0):
-    from urlparse import urlparse
+    from urlparse import urlparse, unquote
 else:
-    from urllib.parse import urlparse
+    from urllib.parse import urlparse, unquote
 
 __all__ = ['CommonMarkParser']
 
@@ -152,7 +152,7 @@ class CommonMarkParser(parsers.Parser):
         url_check = urlparse(destination)
         if not url_check.scheme and not url_check.fragment:
             wrap_node = addnodes.pending_xref(
-                reftarget=destination,
+                reftarget=unquote(destination),
                 reftype='any',
                 refdomain=None,  # Added to enable cross-linking
                 refexplicit=True,
diff --git a/tests/sphinx_xref/conf.py b/tests/sphinx_xref/conf.py
index 6b0140e..443a026 100644
--- a/tests/sphinx_xref/conf.py
+++ b/tests/sphinx_xref/conf.py
@@ -3,6 +3,9 @@
 
 from recommonmark.parser import CommonMarkParser
 
+extensions = 'sphinx.ext.autosectionlabel']
+autosectionlabel_prefix_document = True
+
 templates_path = ['_templates']
 source_suffix = '.md'
 source_parsers = { '.md': CommonMarkParser }
diff --git a/tests/sphinx_xref/index.md b/tests/sphinx_xref/index.md
index a41ebfa..ae1cf55 100644
--- a/tests/sphinx_xref/index.md
+++ b/tests/sphinx_xref/index.md
@@ -3,3 +3,7 @@ Header
 
 A paragraph [link](link) and [absolute link](/link). An [external link](http://www.google.com).
 
+A [ref with spaces][].
+
+
+[ref with spaces]: <link:Section 1>
diff --git a/tests/sphinx_xref/link.md b/tests/sphinx_xref/link.md
index a3fbc9c..e2beb4d 100644
--- a/tests/sphinx_xref/link.md
+++ b/tests/sphinx_xref/link.md
@@ -2,3 +2,7 @@ link
 ====
 
 The link file.
+
+## Section 1
+
+Autosectionlabel will generate a link for this heading at `link:Section 1`.