Suggestion: Automatically wrap code in Markdown code blocks

[MarkEwer]

Situation:

When generating .md files from unit tests that have helper methods or sections that we don't need to appear in the documentation, like the using statements, I have been using collapsed sections to "hide" those things from display unless the person needs to drill into them. But the switching from code blocks to markdown and back as I am adding documentation is a little tedious.

Suggestion:

Add a new comment tag called //md language:{language} that we can add near the top of the file. Having added this tag in the file, the processor can then automatically wrap all code lines in a Markdown code block using the named language. This would save the user from having to add //md ``` to every section of code in the document.

Example:

As an example, consider this unit test:

     //md language:CSharp
     /*md
     # Bootstrap Tests
     This C# class provides unit tests to verify the test framework.
     md*/
     //md{ Using Statements
     using System.Reflection;
     using System.Text.Json;

     namespace MyDomain.Tests;

     public class BootstrapTests
     {
     //md}
     /*md

     This test verifies that the testing framework is functional. 
     The only reason this test exists is just to prove that the 
     testing framework is successfully running the unit tests.

     md*/
       [Fact, Trait("JIRA", "EV-1201")]
       public void AssertTrue()
       {
         Assert.True(true);
       }
     }
     /*md

Then we would get this output:

     # Bootstrap Tests
     This C# class provides unit tests to verify the test framework.

     <details><summary><strong>Using Statements</strong></summary>
     ```csharp
     using System.Reflection;
     using System.Text.Json;
     namespace MyDomain.Tests;

     public class BootstrapTests
     {
     ```
     </details>

     This test verifies that the testing framework is functional. 
     The only reason this test exists is just to prove that the testing 
     framework is successfully running the unit tests.
     ```csharp 
       [Fact, Trait("JIRA", "EV-1201")]
       public void AssertTrue()
       {
         Assert.True(true);
       }
     }
     ```

As you can see from the example, the suggestion is for the parser to identify the sections of code that are not tagged as Markdown and automatically wrap them in a Markdown code block using the default language specified at the top of the file. This enhancement would save some typing and make the unit test source code a bit easier to read.

[dadhi]

@MarkEwer
Hi. Nice surprise seeing someone other than me commenting here :)

So, you are proposing to add automatic insertion of code fences?
I will think about that.

Btw, are you using CsToMd or planning?

[MarkEwer]

Yes, I am suggesting automatic insertion of code fences if the default language comment is present in the file.

I am evaluating CsToMd for my team as an addition to our "living documentation" setup.

[dadhi]

I need to think how to support both explicit and configured fences together. I don't want to redo all my existing docs for this.

[dadhi]

Ok, it seems too ambiguous to decide when to insert the code fence if there are already some code fences specified.
To avoid the confusion, I will introduce code:-- to stop the insertion of the fences. Example:

//md code:cs
var x = 3;
//md code:-- stop the cs fences
//md```js
const y = function() {};
//md```
//md code:cs back to cs

In principle, you may simplify the above code like this:

//md code:cs
var x = 3;
//md code:js
const y = function() {};
//md code:cs back to cs

You probably don't need to worry about the code:-- unless you are working with the existing documentation which uses the explicit code fences, and you don't want to migrate it yet.

[MarkEwer]

Nice! That should work well.On Jan 20, 2025 7:38 AM, Maksim Volkau ***@***.***> wrote: Ok, it seems too ambiguous to decide when to insert the code fence if there are already some code fences specified. To avoid the confusion, I will introduce code:-- to stop the insertion of the fences. Example: //md code:cs var x = 3; //md code:-- stop the cs fences //md```js const y = function() {}; //md``` //md code:cs back to cs In principle, you may simplify the above code like this: //md code:cs var x = 3; //md code:js const y = function() {}; //md code:cs back to cs You probably don't need to fuss about the code:-- unless you are working with the existing documentation which uses the explicit code fences, and you don't want to migrate it yet. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>