Support Markdown syntax via commonmark-hs
#794
Description
@jgm @alexbiehl @gbaz This is following up the discussion in #729.
I'm opening a new issue despite #244 and #570 because I'd like to focus on the particular issues around supporting Markdown syntax via commonmark-hs
.
As per #729 (comment), I've gone ahead and
- implemented instances of
IsBlock
andIsInline
for Haddock'sDoc
(see harpocrates@b12bef2) - implemented a custom inline parser for identifier linking (see harpocrates@4d2566c).
All of this is very quick and dirty (and in a separate branch) - I'm just trying to get a feel for the library. Still it is nice to see end to end results:
module Mark where
-- | An emphasized _foo_ and a linked 'foo'.
-- Some math I like: $\int_{\partial \Omega} \omega = \int_\Omega \partial\omega$
--
-- A list of things:
--
-- 1. First item
--
-- ```
-- some code
-- block
-- ```
--
-- 2. Some sub-items
--
-- * sub-item1
-- * __sub-item2__
--
foo :: Int -> Int
foo = undefined
Output:
@jgm My first impression of the API is very positive: I very much like the idea of slicing the problem along the dimensions of SyntaxSpec
. I definitely think this is going to be extensible enough for Haddock. Some more basic questions:
- What is
Rangeable
for? Is this something Haddock might want (or isrange _ x = x
enough) - What is the motivation for distinguishing
lineBreak
andparagraph
? When are both used? - What is
referenceLinkDefinition
?
@gbaz @alexbiehl How can Haddock start using commonmark-hs
? I am completely unfamiliar with what needs to happen from a vendoring/dependency perspective. More generally, can I start making some PR's to prepare for eventual integration (i.e. small changes to Documentation.Haddock.Types
)?