Discrepancies between live site and github markdown

[jarmokivekas]

Reading through the DuckPAN install documentation https://duck.co/duckduckhack/installing_duckpan I noticed some wierdness on the site:

long dash rendered wrong:

link broken by including the closing parentheses:

Neither of those errors exist in the markdown here on github, it renders as it's supposed to. I'm wondering if the cause is simplly that the site is not up-to-date, or if it's because the markdown is translated to html by a different tool on the site?

[moollaza]

Hi @jarmokivekas ,

Thanks a lot for letting us know about those bugs! We're using https://metacpan.org/pod/Markdent to convert the Markdown to HTML and it can be a little finicky sometimes.

[mwmiller]

it can be a little finicky sometimes

I'd call that a fairly generous interpretation of its workings. :grin: I wonder how much could gowrong with a move to the Text::Markup family.

[mwmiller]

it can be a little finicky sometimes

I'd call that a fairly generous interpretation of its workings. :grin: I wonder how much could go wrong with a move to the Text::Markup family.

[moollaza]

@mwmiller the reason I went with Markdent is because it specifically supports "GitHub Flavoured Markdown" (for example the HTML code blocks all have a classes with the languge specified in the Markdown) That way we can easily introduce syntax highlighting for all the code blocks.

One alternative to Markdent, which I had forgetten, about is that GitHub has an API you can send GFM text to, and it returns the HTML. That method would likely make for a better conversion process, albeit slower.

[mwmiller]

That way we can easily introduce syntax highlighting for all the code blocks.

Not to put too fine a point on it, I think if this were a real priority it likely would have happened by now. On the other hand, you've spent hours understanding and working around all the parser idiosyncrasies.

I guess I should shut up though, as I don't know what all goes into Publisher. :grin:

[moollaza]

hahaha well I had a grand plan for the docs when I started planning it way back, but only some of the features I wanted ended up getting implemented. I'm still holding out for beautiful syntax highlighting!

Regarding Publisher, we mostly went with that because it enabled us to put the docs onto the Comm Plat and because we could then use the Comm Plat templates. One of my earlier ideas was to simply use GitHub Pages for the docs. I'm all ears for a better system :)

[moollaza]

I've fixed these error for now. Will be investigating some alternatives to Markdent. I have a working branch on duckduckgo-publisher that uses an NPM module, "Marked" to do the conversion. From what I could tell it did a fine job of converting but the small bug I noticed was that it was injecting a space (" ") before each line in some code blocks which I couldn't figure out.