4

Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:

/* --> start with multi line comments 
here some markdown text
# heading
 * list

end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)

_-_-indented code
_-_-_-_-more indented code

The issues are:

  • the first /* still showing in the documentation
  • I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.

I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?

Foad S. Farimani
  • 12,396
  • 15
  • 78
  • 193
  • 1
    This is a great question. I want to do something similar for easy literate programming. But one of the big issues I have is with how to deal with shebangs. And other boundary condition issues. The answer here is a good starting point though it seems. – Steven Lu Aug 01 '20 at 19:50

1 Answers1

2

I think I have a proper solution now with colapsible / foldable code section: 

/*

This is the markdown **text** 

used for documentation

<details>
  <summary>Click to see the source code</summary>

``` scilab 
*/
This is the
  actual code
  which will 
be executed
/*
```

</details>

<!--- */ // -->

which will be rendered as:

/*

This is the markdown text

used for documentation

*/
This is the
  actual code
  which will 
be executed
/*

The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.

P.S. Implementation of the same idea using AsciiDoc here.

Foad S. Farimani
  • 12,396
  • 15
  • 78
  • 193
  • 1
    I think the solution will depend on which Markdown parser is being used (because of the handling of the embedded HTML for instance), but glad you got something working for you. – ShreevatsaR Mar 14 '19 at 13:18
  • true. this only renders on github and vscode, but not Stackoverflow and Typora. – Foad S. Farimani Mar 14 '19 at 17:19
  • 1
    I was able to innovate on this slightly by being able to properly hide the initial `*/` showing in the code blocks, and to be able to show `//` or `////////////` at the beginning of the file (which is ok since you can use it like decoration) but it seems inescapable to have those at the ends of code blocks, which I can't stand... This makes me kinda sad because otherwise it's pretty capable. – Steven Lu Aug 01 '20 at 21:28