Sublime Forum

Markdown syntax highlighting in source code comments

#1

I often write code comments in markdown formatting.

With the MarkdownEditing plugin I’ve got some lovely styling set up on markdown, but in code comments I just get generic text formatting.

Is it possible to enable markdown syntax highlighting in code comments?

Specifically, I’m working in PHP and JS if it makes any impact on the answer.

0 Likes
#2

Adding support for inline formattings may be doable, but supporting the whole Markdown syntax including lists, tables, headings, etc. is rather likely to not work well together with leading * or // comment markers in multi-line comments.

0 Likes
#3

I’m not bothered about // lines, and I’d be happy for it to work without leading * on /* … */ blocks – my multi-line comments with leading * tend to be formal structured blocks.

How would I start getting this working?

0 Likes
#4

The way PHP and JS are bundled and used as base for all sorts of other syntaxes, the only viable way to was to override original syntax files and apply some patch to them.

Disclaimer

It however comes with a risk of missing updated or breaking syntaxes upon ST updates.

Steps

  1. Extract PHP/PHP Source.sublime-syntax (maybe using OverrideAudit)

  2. apply the following patch to embed Markdown into comment bodies.

    diff --git a/PHP/PHP Source.sublime-syntax b/PHP/PHP Source.sublime-syntax
index 63db705f..51aae3d5 100644
--- a/PHP/PHP Source.sublime-syntax	
+++ b/PHP/PHP Source.sublime-syntax	
@@ -586,14 +586,22 @@ contexts:
         - comment-phpdoc-end
         - phpdoc-block-tag
     - match: /\*
-      scope: punctuation.definition.comment.begin.php
-      push: comment-block-body
+      scope: comment.block.php punctuation.definition.comment.begin.php
+      embed: scope:text.html.markdown#indented-markdown
+      embed_scope: comment.block.php text.html.markdown
+      escape: \*/
+      escape_captures:
+        0: comment.block.php punctuation.definition.comment.end.php
     - match: //
       scope: punctuation.definition.comment.php
-      push: comment-line-double-slash-body
+      embed: scope:text.html.markdown#inlines
+      embed_scope: comment.line.double-slash.php text.html.markdown
+      escape: $
     - match: '#'
       scope: punctuation.definition.comment.php
-      push: comment-line-number-sign-body
+      embed: scope:text.html.markdown#inlines
+      embed_scope: comment.line.number-sign.php text.html.markdown
+      escape: $
 
   comment-block-body:
     - meta_include_prototype: false

  3. Extract JavaScript/JavaScript.sublime-syntax

  4. Apply the following patch

    diff --git a/JavaScript/JavaScript.sublime-syntax b/JavaScript/JavaScript.sublime-syntax
index f7df3a31..e7efa510 100644
--- a/JavaScript/JavaScript.sublime-syntax
+++ b/JavaScript/JavaScript.sublime-syntax
@@ -139,8 +139,12 @@ contexts:
         - jsdoc-block-tag
     # normal block comments
     - match: /\*
-      scope: punctuation.definition.comment.begin.js
-      push: block-comment-body
+      scope: comment.block.js punctuation.definition.comment.begin.js
+      embed: scope:text.html.markdown#indented-markdown
+      embed_scope: comment.block.js text.html.markdown
+      escape: \*/
+      escape_captures:
+        0: comment.block.js punctuation.definition.comment.end.js
 
   block-comment-end:
     - match: \*+/

Result

grafik

0 Likes
#5

Oh my days, thank you so much! That is so amazing, perfect for what I need!
That will make life a little easier for me every day! :smiley:

And thanks for introducing me to OverrideAudit, that is a very useful tool, and opens the doors for me to solve something like this myself next time.

0 Likes