Add hint about inline link issue (#1444)

1 files changed, 11 insertions, 0 deletions

diff --git a/doc/markup.rst b/doc/markup.rst
index c0b08a40..3d5bf12a 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -1121,6 +1121,17 @@ followed by the URL enclosed in regular parentheses, for example: ::
 The link text is used as a description for the URL if the output
 format supports it.
 
+Hint: There's a `known issue <https://github.com/haskell/haddock/issues/774>`_ 
+that any inline link at the beginning of a line within a multi-line comment 
+isn't rendered correctly: ::
+   
+    {-| Some multi-line comment that has a
+    [link](https://example.com) and a
+    [reference link]: https://example.com
+    -}
+    
+Adding a space or a word in front of such a link can be used as a workaround.   
+   
 Images
 ~~~~~~