aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CHANGES2
-rw-r--r--doc/haddock.xml19
-rw-r--r--haddock-library/src/Documentation/Haddock/Parser.hs12
-rw-r--r--haddock-library/test/Documentation/Haddock/ParserSpec.hs24
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