supporting ``` would be really great

[gmabey]

It looks like imposing monospace on in-line text with back-ticks works great, but escaping entire blocks with ``` doesn't. Do you plan to support that eventually?

[markvincze]

Hi @gmabey,

I tested it now, and indented code blocks already work, so in the main page content you can do this:

This is an indented code block:

    namespace Test
    {
        public class Foo {
            public string Bar { get; set; }
        }
    }

Or in a proto file comment:

// This is the comment for SearchRequest.
//
// This is an indented code block:
//
//     namespace Test
//     {
//         public class Foo {
//             public string Bar { get; set; }
//         }
//     }
message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 results_per_page = 3;
}

I'll investigate whether fenced code blocks could also be supported.

[markvincze]

@gmabey I implemented support for the ``` fenced code blocks as well in #26

[markvincze]

@gmabey Closing this now, feel free to reply if it's not working correctly.

[gmabey]

So, fenced code blocks does work now, but it seems to not be any different than single-backtick. That is, in my comment block, the section marked in this way appears in-line with the other paragraph content, unless I add a blank line around it (before and after). That's not quite the behavior I was hoping for (instead I was hoping for a new paragraph to be implicit to the triple-backtick). Is that consistent with the behavior you intended to implement?

[markvincze]

@gmabey Not sure, with the current implementation, we're at the mercy of the capabilities of the Markdown package, we render the output in the way how this library converts it to HTML. In the fix I implemented, I did not add any custom implementation for the fenced code blocks, but just added the extensions=['fenced_code'] parameter to the call to the library.

My preferred way would be if it worked the way you're describing, that the code block should be correctly rendered even if there are no empty lines before and after. I'll try to check if something can be changed in the configuration of Markdown to make it work that way, or if we can switch to another Markdown renderer.

[markvincze]

@gmabey Could you verify one thing? Might it be that the issue only happens if there are leading spaces in the comment lines?

Because I could reproduce it if my comment looked like this:

// This is a comment for SearchRequest.
// This is the paragraph before a code block.
// ```
// class Person {
//     string Name;
// }
// ```
// This is the paragraph after the code block.

But if I delete the leading spaces, it works correctly.

//This is a comment for SearchRequest.
//This is the paragraph before a code block.
//```
//class Person {
//    string Name;
//}
//```
//This is the paragraph after the code block.

Does this fix the issue for you as well? Because then I can do a code change to automatically trim these leading spaces from every line.

[markvincze]

@gmabey I made an attempt at implementing a fix, it's released in 0.11.555.dev0 (not sure if it's fully correct yet though). Can you try if that changes the behavior for you?

[gmabey]

I switched to the trim-markdown-leading-spaces branch and tried it there, but I don't see any difference in the behavior.

[markvincze]

@gmabey Ah, I see, I didn't even think of block comments, as I almost never use those, that's a new complication 😅

I'm wondering if maybe somehow an older version of the CLI is getting used in your test. Because I tried it with this Proto:

And this is the rendered output, the fenced code block is working:

So I'm thinking that maybe in your test an older version of the CLI is used, in which the config for supporting the fenced code blocks was not yet added?

However, I think that this will not work correctly with block comments anyway, because apparently with blocked comments, protoc automatically removes all the leading whitespace. Which means that even if the fenced code block is rendered as a code block, all the indentation is lost.

I'll add a mention about this in the README, that the indentation is only preserved if single-line comments are used

[gmabey]

I now have validated that this is also working as expected too.