Add support for markdown images

4 files changed, 34 insertions, 23 deletions

diff --git a/CHANGES b/CHANGES
index 009d63fe..4bfe492c 100644
--- a/CHANGES
+++ b/CHANGES
@@ -2,6 +2,8 @@ Changes in version 2.15.1
 
  * Experimental collapsible header support (#335)
 
+ * Add support for markdown links and images
+
 Changes in version 2.15.0
 
  * Always read in prologue files as UTF8 (#286 and Cabal #1721)
diff --git a/doc/haddock.xml b/doc/haddock.xml
index 1fece5b3..ee77ede9 100644
--- a/doc/haddock.xml
+++ b/doc/haddock.xml
@@ -2118,17 +2118,20 @@ This belongs to the list above!
 
       <section>
         <title>Images</title>
+        <para>
+            Haddock supports Markdown syntax for inline images.  This resembles
+            the syntax for links, but starts with an exclamation mark.  An
+            example looks like this:
+        </para>
 
-        <para>An image can be included in a documentation comment by
-        surrounding it in double angle brackets:
-        <literal>&lt;&lt;...&gt;&gt;</literal>.  If the output format supports
-        it, the image will be rendered inside the documentation.</para>
-
-        <para>Title text can be included using an optional label:</para>
 <programlisting>
-&lt;&lt;pathtoimage.png title&gt;&gt;
+![image description](pathtoimage.png)
 </programlisting>
-
+        <para>
+          If the output format supports it, the image will be rendered inside
+          the documentation.  The image description is used as relpacement text
+          and/or image title.
+        </para>
       </section>
 
       <section>
diff --git a/haddock-library/src/Documentation/Haddock/Parser.hs b/haddock-library/src/Documentation/Haddock/Parser.hs
index f1fd5dda..ff03c7bb 100644
--- a/haddock-library/src/Documentation/Haddock/Parser.hs
+++ b/haddock-library/src/Documentation/Haddock/Parser.hs
@@ -102,7 +102,7 @@ parseStringBS = parse p
   where
     p :: Parser (DocH mod Identifier)
     p = docConcat <$> many (monospace <|> anchor <|> identifier <|> moduleName
-                            <|> picture <|> hyperlink <|> bold
+                            <|> picture <|> markdownImage <|> hyperlink <|> bold
                             <|> emphasis <|> encodedChar <|> string'
                             <|> skipSpecialChar)
 
@@ -209,6 +209,11 @@ picture :: Parser (DocH mod a)
 picture = DocPic . makeLabeled Picture . decodeUtf8
           <$> disallowNewline ("<<" *> takeUntil ">>")
 
+markdownImage :: Parser (DocH mod a)
+markdownImage = fromHyperlink <$> ("!" *> linkParser)
+  where
+    fromHyperlink (Hyperlink url label) = DocPic (Picture url label)
+
 -- | Paragraph parser, called by 'parseParas'.
 paragraph :: Parser (DocH mod Identifier)
 paragraph = examples <|> skipSpace *> (
@@ -467,7 +472,10 @@ hyperlink = DocHyperlink . makeLabeled Hyperlink . decodeUtf8
             <|> markdownLink
 
 markdownLink :: Parser (DocH mod a)
-markdownLink = DocHyperlink <$> (flip Hyperlink <$> label <*> (whitespace *> url))
+markdownLink = DocHyperlink <$> linkParser
+
+linkParser :: Parser Hyperlink
+linkParser = flip Hyperlink <$> label <*> (whitespace *> url)
   where
     label :: Parser (Maybe String)
     label = Just . strip . decode <$> ("[" *> takeUntil "]")
diff --git a/haddock-library/test/Documentation/Haddock/ParserSpec.hs b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
index 6d152ee2..4373234c 100644
--- a/haddock-library/test/Documentation/Haddock/ParserSpec.hs
+++ b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
@@ -183,24 +183,22 @@ spec = do
           "foo https://example.com/example bar" `shouldParseTo`
             "foo " <> hyperlink "https://example.com/example" Nothing <> " bar"
 
-    context "when parsing pictures" $ do
-      let picture :: String -> Maybe String -> Doc String
-          picture uri = DocPic . Picture uri
+    context "when parsing images" $ do
+      let image :: String -> Maybe String -> Doc String
+          image uri = DocPic . Picture uri
 
-      it "parses a simple picture" $ do
-        "<<baz>>" `shouldParseTo` picture "baz" Nothing
+      it "accepts markdown syntax for images" $ do
+        "![label](url)" `shouldParseTo` image "url" "label"
 
-      it "parses a picture with a title" $ do
-        "<<b a z>>" `shouldParseTo` picture "b" (Just "a z")
+      it "accepts Unicode" $ do
+        "![灼眼のシャナ](url)" `shouldParseTo` image "url" "灼眼のシャナ"
 
-      it "parses a picture with unicode" $ do
-        "<<灼眼のシャナ>>" `shouldParseTo` picture "灼眼のシャナ" Nothing
+      it "supports deprecated picture syntax" $ do
+        "<<baz>>" `shouldParseTo` image "baz" Nothing
 
-      it "allows for escaping of the closing tags" $ do
-        "<<ba\\>>z>>" `shouldParseTo` picture "ba>>z" Nothing
+      it "supports title for deprecated picture syntax" $ do
+        "<<b a z>>" `shouldParseTo` image "b" "a z"
 
-      it "doesn't allow for multi-line picture tags" $ do
-        "<<ba\nz aar>>" `shouldParseTo` "<<ba\nz aar>>"
 
     context "when parsing anchors" $ do
       it "parses a single word anchor" $ do