stephenharris/wp-readme-to-markdown

Code snippets on multiple lines

marcochiesi opened this issue · 6 comments

marcochiesi commented

WP and Github have different syntax for code snippets on multiple lines. Would it be possible to convert them? I suppose it would be sufficient to replace lines containing only a single backquote with three backquotes.

See example:

stephenharris commented

Just to confirm, WP.org uses single backtics on their own line as a codeblock (same forums)? Do you happen to know what happens if space is included before/after the backtics?

stephenharris commented

Just a note to add that three backtics wouldn't be the right thing. That is "Github-flavoured" markdown, and although I dare say that most uses of this task (including mine) is to have a nicely formatted readme on GitHub, I very keen to stick to the markdown standard... which is unfortunately and bit more tricky...

stephenharris commented

Added commit, but that obviously won't work, as code inside won't be escaped... getting each line indented is beyond me today. I'll take another look, but you are welcome to have a go yourself ;)

marcochiesi commented

I can confirm that single backticks in readme.txt are rendered as codeblocks.

I made some test with the WP readme validator, which I am not 100% sure behaves exactly the same as the readme renderer of the repo, but I suppose it does. The results were as following:

  • Spaces that precede the single backtick break things
  • Spaces that follows the single backtick do not break things

So I think that only single backticks at the beginning of a line should be converted in triple backticks in the MD file.

As for the "Github-flavoured" markdown, I understand your point, but as you said, most uses of this package are aimed to have a good README.md for Github. I think you may implement this feature and leave it as an option which is disabled by default. This way it won't break things, but at the same time who wants to use it will be able to do it.

marcochiesi commented

Thanks for your effort. I tried your last commit and it seems it only replaces the first codeblock (g modifier needed), besides not using the triple backticks.
I was able to let it work just by changing your replace call with the following:

readme = readme.replace( new RegExp("^`\\s*$", "gm"), "```");
stephenharris commented

Finally got round to doing this :). Thanks @marcochiesi for your comments regarding the global modifier.

This latest update formats codeblocks according to standard markdown (rather than wrapping in HTML tags or GitHub's three backtics. Although some people (including myself) prefer backtics to indentation, this is an auto-generated file which shouldn't normally be edited, so all that matters is that it is properly formatted.

Feedback welcome, else in a few days I'm going to hit publish on this for the npm repository.

Caveats

As noted in the readme there is some caveats to this. I noticed some unexpected behaviour regarding backtics and codeblocks (according to the validator linked to above). Here's summary:

  • Inline code must be enclosed by single backtics, and must not contain an empty line.
  • Codeblocks should be enclosed by single backtics, the first one of which must be the first character on the line and the enclosed content must contain a newline.

Four examples to illustrate

`inline` and this is `also inline`

`function thisIsACodeBlock(){
}`

This `function isInline(){
}`

This `function isNeither(){

}`

So what's the caveat?

Currently this plug-in ignores examples like (2). This may change, but for the time being please ensure your readme.txt code blocks are formatted so that the backtics are on their own line:

`
function thisIsACodeBlock(){
}
`