Syntax inheritance and the "extends" key

[dutch]

[My usual disclaimer: I’m not a programmer, but a prose writer. I like tweaking ST, but I’m a rank beginner.]

Using the Inheritance instructions from the official ST documentation, I’m trying to employ the extends key to associate a small syntax tweak (which OdatNurd taught me how to create a couple years ago–see below) with ST’s Markdown.sublime-syntax definition.

Goal: I want this little syntax tweak to work along with ST’s stock Markdown syntax. As it stands now, I can have one or the other; I want both.

The extends key requires the path to the parent syntax. I couldn’t find that path, as Markdown.sublime-syntax doesn’t appear in Packages.

In an attempt to sidestep that circumstance, I opened Markdown.sublime-syntax via PackageResourceViewer: Open Resource and re-saved it, which created a copy in my Packages directory.

I then used the path to the instance of Markdown.sublime-syntax in my Packages directory as the extends key within my little syntax file.

Alas, it didn’t do the trick.

A couple of questions:

1. Am I on the right track? Should I be able to make this little custom syntax tweak work in conjunction with the full markdown syntax definition that ships with ST? Is there a better/easier way to accomplish what I’m trying to accomplish?

2. What is the path to ST’s Markdown.sublime-syntax? (i.e., without my opening it via PackageResourceViewer and re-saving it, it doesn’t appear in my Packages directory).

THANKS

Here’s the syntax file I’m working with. It works as is, but only on its own. Again, I want this functionality to function in, or alongside, the main Markdown syntax. NOTE: This copy includes the extends key that I tried but which didn’t work.

%YAML 1.2
---

file_extensions:
  - md
  - mdown
  - mdwn
  - markdown
  - markdn
scope: text.md
name: my md highlighting tweak
extends: Packages/Markdown/Markdown.sublime-syntax
contexts:
  main:
    - match: '@@ '
      scope: punctuation.definition.note.comment.begin
      push:
      - meta_scope: note.text.comment  
      - match: ' @@'
        scope: punctuation.definition.note.comment.end
        pop: true

    - match: '&& '
      scope: punctuation.definition.note.header.begin
      push:
      - meta_scope: note.text.header
      - match: ' &&'
        scope: punctuation.definition.note.header.end
        pop: true

[OdatNurd]

The syntax that you want is something along the lines of the below one.

You actually had the right idea (and the right path for the core Markdown syntax as well), but there were a couple of issues with what you had going there.

• The internal markdown syntax is version: 2, so in order to extend it yours also needs to be version: 2 as well; otherwise you get an error
• The context that you want to use here is markdown and not main, and an extra meta key is required,

Regarding the first item, the version of the syntax is important because it changes some default assumptions (which are in the syntax docs) in a way that could cause issues, so all syntax elements have to be “in agreement” with the rules, as it were.

For the second part, this is a two-fer.

If you use the same context name as a context that exists in the parent syntax, you will replace it UNLESS you use one of the two meta keys that are available for this; one that says that your content should be inserted before the default, and one that says it should be after.

Here it’s a prepend so that your rules take effect before the defaults; if you use append here, they get added on the end of the list, but they will never trigger because rules in the main syntax will consume the input before you can see it.

The other thing that you have an issue with here is the context that you’re using. This is entirely a case by case basis, but if you use View Package File to look at Packages/Markdown/Markdown.sublime-syntax, the contexts look like this:

contexts:

  main:
    - include: frontmatter
    - match: ''
      set: markdown

Based on that, it doesn’t matter what you add to main, either before or after, because the match is going to immediately force the markdown context.

So the result is something like the following. This will only allow your comments top level though; so there may be additional tweaking required.

%YAML 1.2
---

file_extensions:
  - md
  - mdown
  - mdwn
  - markdown
  - markdn
scope: text.md
version: 2
name: my md highlighting tweak
extends: Packages/Markdown/Markdown.sublime-syntax
contexts:
  markdown:
    - meta_prepend: true
    - match: '@@ '
      scope: punctuation.definition.note.comment.begin
      push:
      - meta_scope: note.text.comment
      - match: ' @@'
        scope: punctuation.definition.note.comment.end
        pop: true

    - match: '&& '
      scope: punctuation.definition.note.header.begin
      push:
      - meta_scope: note.text.header
      - match: ' &&'
        scope: punctuation.definition.note.header.end
        pop: true

[dutch]

Thanks a ton, man. I’m working through it now. It’s not happening yet, but I need to go through everything closely and make sure I’m implementing correctly. With a little luck, I should get there, and I’ll report results. One question: What do you mean this will only allow my comments “top level”?

[deathaxe]

Are those extensions meant to be used inline with text? If yes, the context to prepend those patterns to would be inlines.

[dutch]

Thanks, deathaxe. Switching in inlines for markdown fixed it; they were sort of half-working before I made that change, and I was pretty much as a loss.

One other thing has changed–not related to your “inlines” change, but after I switched out my old syntax for OdatNurd’s new one: Markdown’s native commenting function has stopped working. I’m guessing by putting this new comment-related syntax chunk in the mix, we’ve maybe superseded the native commenting function. I’m poking around on it…

Thanks again for the help. Much appreciated.

[dutch]

This solution, with deathaxe’s “inlines” adjustment, is working for me and I’m grateful for the help. I have a couple follow-up questions, though, because there are a couple of anomalies. Well, the first is a statement; the second’s a question.

1. Confirming what I noted yesterday: This solution seems to have wiped out the MD syntax’s native “comment” feature. This is not a problem, as the solution you’ve helped me with is a commenting feature itself, and a better one for my purposes. And it’s one I’ve grown used to over a couple years in my txt-only files. This rewrite for MD format will do the trick for me in most of my project.

2. However, I can’t get this md tweak to work in projects that use just a slightly changed color scheme. I have a “notes” format I use for some projects, and the project settings looks like this:

   {
   “folders”:
   [
   {
   “path”: “practicing_notes”
   }
   ],
   “settings”: {“color_scheme”: “Packages/User/Monokai_notes.sublime-color-scheme”,
   },
   }

I can’t see anything in my “Monokai_notes” color scheme that would interfere with implementing my MD tweaks. But md files in those notes projects, with “my_md_tweaks” syntax applied to them, do not function as md files. FWIW, here’s that Monokai_notes color scheme:

{
    "variables":
    {      
        "yellow_main_text": "hsl(53, 78%, 45%)",
        //this is supposedly yellow #2 pencil color
        "yellow_pencil": "hsl(36, 76%, 52%)",
        "red_dark": "hsl(0, 100%, 25%)",
        "black": "hsl(70, 0%, 8%)",
        "blue_nice": "hsl(233, 78%, 45%)",
        "orange": "hsl(24, 100%, 50%)",
        "blue_text": "hsl(170, 100%, 45%)",
        "blue_highlight": "hsl(170, 100%, 15%)",        
    },
    "globals":
    {
        //main text background and font colors
        "background": "var(black)",
        "foreground": "var(blue_text)",        
        //gutter_foreground is line-number color in gutter
        "gutter_foreground": "var(yellow_pencil)",        
        //line_highlight is the block that highlights in the gutter wherever you are in the file.
        "line_highlight": "var(blue_highlight)",        
        //diff marker stuff
			"line_diff_added": "var(yellow_pencil)",
			"line_diff_modified": "var(yellow_pencil)",
			"line_diff_deleted": "var(blue_nice)",
			"line_diff_width": "3",
        "caret": "color(var(orange) alpha(0.9))",
    },
    "rules":
    [
        {
            "scope": "text.md note.text.comment",
            "foreground": "black",
            "background": "var(blue_text)",
        }, 	
	{
            "scope": "text.md note.text.header",
            "foreground": "black",
            "background": "red",
        },
    ]
}

Based on my past history, I’m sure I’m missing something blindingly obvious. Any ideas why my “notes” projects aren’t implementing my md syntax?

[deathaxe]

Native comments no longer work as those are just HTML comments.

They are not triggered as main scope doesn’t start with text.html but with text.md.

Default Markdown uses text.html.markdown main scope. So your’s should probably use something like text.html.markdown.my-private-one to make sure to keep all basic html/md functionality enabled.

my-private-one can be replaced by anything meaningful word, so the whole string becomes unique.

This should also resolve most/all color scheme related issues, you’ve encountered.

[dutch]

Thanks, deathaxe. I’m not sure how to apply that suggestion, though. I barely understand scopes to begin with, sorry to say. Do you mean I should replace the text.md scope of my little syntax tweak to something like text.html.markdown.my-private-one, or make that change somewhere else? I tried it in my syntax, and my custom commenting wouldn’t work at all.

[dutch]

Maybe this will help, maybe not, but I’ve narrowed the problem down, I think.

So, as I said, I have this particular project that is not allowing me to apply my_md_tweak (or any other syntax for that matter) to its .md files.

The setting file for that project includes this:

“settings”: {“color_scheme”: “Packages/User/Monokai_notes.sublime-color-scheme”,

…which gives me the primary text/background colors I want, but seems to be blocking me from applying syntaxes.

Perhaps this is because it’s not called “Monokai.sublime-color-scheme”? But I can’t name it that because I already have a version with that name in my User folder, which contains my customizations for most of my other projects. I want my notes project to have different colored main text, but I also want to be able to apply md syntax def to it.

Have I isolated the problem? What to do?

[dutch]

A quick FYI just in case anyone’s been following this.

I’ve capitulated. I’m no longer interested in getting my little syntax tweak (my custom-commenting feature) to work with my new .md-focused setup. Mostly because the more I thought about it, and the longer I experimented with the Markdown color possibilities, the more I realized I could easily live without my custom feature. And being able to use ST’s core Markdown syntax instead of scotch-taping other pieces together just seems a more solid choice for a guy like me–i.e., a prose writer, not a programmer. As a solution, it’s going to be a lot less fiddly.

I’ve got Markdown’s color scheme doing what I want, using H1, H2, H3 tags as various kinds of markers in my text. I’ve also got its commenting feature working and looking the way I want it to.

I was able to associate a second color scheme with my “notes” project and color it the way I like. So I’ve got a custom Monokai scheme on most of my primary drafting projects and a custom Mariana scheme on the companion notes projects that often accompany my drafts, and I can pull up those two projects–a draft and its notes–side by side, which is how I like to work.

So, a Gordian Knot solution to my original problem posed above, and a pleasing simplicity.

As always, I appreciate the help I get here.