I'm trying to document a codebase in markdown, and finding it difficult to include links inside my code examples. If I were writing HTML, I'd write: <code>perl <a href="https://daringfireball.net/projects/markdown/">Markdown.pl</a> < input.md</code> But, there doesn't seem to be a way to achieve this in Markdown, because any markup i include inside backticks gets HTML encoded (as it should). The closest I can do in markdown is: `perl` [`Markdown.pl`](https://daringfireball.net/projects/markdown/) `< input.md` Which renders as <p><code>perl</code> <a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a> <code>< input.md</code></p> but is fraught with style issues. Not only is a space a different width outside <code>, but the theme I'm using puts a background and borders on code tags. As a workaround, would you be willing to allow _DoCodeSpans to preserve leading & trailing white space inside the backticks? --- Markdown.pl.orig 2018-08-24 08:47:13.603707569 -0400 +++ Markdown.pl 2018-08-24 08:48:46.949349781 -0400 @@ -983,8 +983,6 @@ (?!`) @ my $c = "$2"; - $c =~ s/^[ \t]*//g; # leading whitespace - $c =~ s/[ \t]*$//g; # trailing whitespace $c = _EncodeCode($c); "<code>$c</code>"; @egsx; With this patch, markdown like this: `perl `[`Markdown.pl`](https://daringfireball.net/projects/markdown/)` < input.md` renders as <p><code>perl </code><a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a><code> < input.md</code></p> with the whitespace inside the <code> and no space between the </code> and the <a>, making it easier to clean up the look of the resulting webpage with CSS. Thanks very much for your time & for Markdown. -Dan
Dan, A few comments: 1. Probably the best way to do this in Markdown (and variants) is exactly how you did it in HTML:> <code>perl <a href="https://daringfireball.net/projects/markdown/">Markdown.pl</a> < input.md</code>It's more easily understood than the alternative you use, and more amenable to "post-processing" of your document that could conceivable occur (e.g. "I want to scrape all code fragments for another use"). And it works better with CSS as you yourself note. 2. The only reason I see for *not* doing this is if you are looking to export to other formats from a single source Markdown document (e.g. LaTeX, OpenDocument, etc.) If you're using Markdown.pl, that doesn't apply. 3. "Markdown the syntax" is alive and well across many spin-off projects. 4."Markdown.pl the implementation" hasn't been updated in almost 14 years (Dec 2004 for v 1.0.1). No new features or fixes for long-standing bugs. You're unlikely to see any new releases from Gruber based on his prior public comments. Based on #1 above, I would not recommend modifying Markdown.pl as your request, but if you insist you could do it yourself. 5. Updates and bug-fixes notwithstanding, Markdown.pl has been far surpassed by multiple other Markdown projects in terms of performance. I don't recommend that anyone use Markdown.pl any more, except for the most trivial of use cases. There are too many good alternatives out there. (I am, of course, biased about which of the *Multi*ple *Markdown* implementations I would recommend.... ;) (Couldn't resist the ridiculous pun there....) 6. A search of the archives (https://pairlist6.pair.net/pipermail/markdown-discuss/ <https://pairlist6.pair.net/pipermail/markdown-discuss/>) will reveal that this mailing list is all but dead. You'll probably reach a few diehard Markdown supporters and people who simply forgot to unsubscribe. But you may find more active help using the support channels specific to a particular (active) Markdown implementation if you don't get sufficient help here. My $.02, Fletcher -- Fletcher T. Penney fletcher at fletcherpenney.net> On Aug 24, 2018, at 9:21 AM, Dan <markdown-discuss at drmoose.net> wrote: > > I'm trying to document a codebase in markdown, and finding it difficult to include links inside my code examples. If I were writing HTML, I'd write: > > <code>perl <a href="https://daringfireball.net/projects/markdown/">Markdown.pl</a> < input.md</code> > > But, there doesn't seem to be a way to achieve this in Markdown, because any markup i include inside backticks gets HTML encoded (as it should). The closest I can do in markdown is: > > `perl` [`Markdown.pl`](https://daringfireball.net/projects/markdown/) `< input.md` > > Which renders as > > <p><code>perl</code> <a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a> <code>< input.md</code></p> > > but is fraught with style issues. Not only is a space a different width outside <code>, but the theme I'm using puts a background and borders on code tags. > > As a workaround, would you be willing to allow _DoCodeSpans to preserve leading & trailing white space inside the backticks? > > --- Markdown.pl.orig 2018-08-24 08:47:13.603707569 -0400 > +++ Markdown.pl 2018-08-24 08:48:46.949349781 -0400 > @@ -983,8 +983,6 @@ > (?!`) > @ > my $c = "$2"; > - $c =~ s/^[ \t]*//g; # leading whitespace > - $c =~ s/[ \t]*$//g; # trailing whitespace > $c = _EncodeCode($c); > "<code>$c</code>"; > @egsx; > > With this patch, markdown like this: > > `perl `[`Markdown.pl`](https://daringfireball.net/projects/markdown/)` < input.md` > > renders as > > <p><code>perl </code><a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a><code> < input.md</code></p> > > with the whitespace inside the <code> and no space between the </code> and the <a>, making it easier to clean up the look of the resulting webpage with CSS. > > Thanks very much for your time & for Markdown. > -Dan > _______________________________________________ > Markdown-Discuss mailing list > Markdown-Discuss at six.pairlist.net > https://pairlist6.pair.net/mailman/listinfo/markdown-discuss-------------- next part -------------- An HTML attachment was scrubbed... URL: <https://pairlist6.pair.net/pipermail/markdown-discuss/attachments/20180824/864b11f5/attachment-0001.html>
Hi Dan, * Dan <markdown-discuss at drmoose.net> [2018-08-24 15:29]:> I'm trying to document a codebase in markdown, and finding it > difficult to include links inside my code examples. If I were writing > HTML, I'd write: > > <code>perl <a href="https://daringfireball.net/projects/markdown/">Markdown.pl</a> < input.md</code>that?s exactly what you should write in Markdown as well. Markdown is HTML. There is a reason it doesn?t have as much syntax as things like Textile and reStructuredText and it?s right there in the name: unlike these others, Markdown is *not* a markup language. It?s just HTML with some shorthand notations on top. That?s why it allows you to just write HTML tags in your text as if it was HTML? because, it is. So if there is no shorthand notation that does what you need, just use the long form: HTML tags. Consider the reason that Markdown has the backtick code span syntax: because HTML makes it difficult to write about code ? because you need to entity-escape some very common characters. To fix that problem, the shorthand syntax must disallow markup inside code, so that no characters have special meaning, so that no characters need to be escaped. Now consider your use case: you *want* to put markup inside your code. That means you need *some* way to make *some* characters special. That means your particular use case contradicts the requirements for the code span shorthand. Now, it would be possible to try and shoehorn something into the syntax that would make it worse for its purpose (because suddenly you have to escape some characters) but would allow putting markup into code. But wait? marking up code is already what HTML is good at. So this would just be a poor reinvention of HTML. Your use case is already covered perfectly well by what HTML by itself already allows. So, just use the HTML way of writing it. HTML is the right tool for your job.> But, there doesn't seem to be a way to achieve this in Markdown, > because any markup i include inside backticks gets HTML encoded (as it > should). The closest I can do in markdown is: > > `perl` [`Markdown.pl`](https://daringfireball.net/projects/markdown/) > `< input.md` > > Which renders as > > <p><code>perl</code> <a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a> <code>< input.md</code></p> > > but is fraught with style issues. Not only is a space a different > width outside <code>, but the theme I'm using puts a background and > borders on code tags. > > As a workaround, would you be willing to allow _DoCodeSpans to > preserve leading & trailing white space inside the backticks? > > --- Markdown.pl.orig 2018-08-24 08:47:13.603707569 -0400 > +++ Markdown.pl 2018-08-24 08:48:46.949349781 -0400 > @@ -983,8 +983,6 @@ > (?!`) > @ > my $c = "$2"; > - $c =~ s/^[ \t]*//g; # leading whitespace > - $c =~ s/[ \t]*$//g; # trailing whitespace > $c = _EncodeCode($c); > "<code>$c</code>"; > @egsx; > > With this patch, markdown like this: > > `perl `[`Markdown.pl`](https://daringfireball.net/projects/markdown/)` < input.md` > > renders as > > <p><code>perl </code><a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a><code> < input.md</code></p> > > with the whitespace inside the <code> and no space between the </code> > and the <a>, making it easier to clean up the look of the resulting > webpage with CSS.That request would break other Markdown syntax. Did you know you can write `` ` `` characters inside code spans without escaping them? Your patch would make that translate into <code> ` </code> which makes this feature pretty useless. This design is because after disallowing all markup inside code spans, there is still one remaining problem with not requiring the author to escape anything inside code spans: how do you make it possible to write backticks inside code spans? And without requiring them to be escaped? Markdown?s answer is: by allowing code spans to be delimited not just with single backticks but by a sequence of backticks of whatever length the author wants. Then the author can just write a greater number of backticks as a delimiter than there are any backticks in a row anywhere in the code, and then nothing in the code needs to be escaped. But if the code itself starts with a backtick, how is Markdown to know where the delimiter ends and the code starts? You have to set apart the end of the delimiter and the start of the code. The obvious way to do that is to put a space between the delimiter and the code. *However* ? and now we finally get to the problem with your proposal ?, this space is not part of the code. It?s part of the delimiter. It only exists in the document because of the Markdown syntax rules, not because it is part of the code. So it *must not* be in the output. And that is why your patch to _DoCodeSpans is wrong. Now, it might be possible to salvage your proposal by introducing an exception, that trimming spaces from code spans only applies when more than a single backtick is used as the delimiter. But that would make the rules more complicated, and it only allows you to use your workaround, which is pretty cruddy anyway ? you?re writing multiple code spans where there really is only one piece of code. Write it with HTML tags. That?s really your answer. Regards, -- Aristotle Pagaltzis // <http://plasmasturm.org/>