@cssdoc/grammarkdown-tmlanguage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @cssdoc/grammarkdown-tmlanguage
+
+A small TextMate grammar for [grammarkdown](https://github.com/rbuckton/grammarkdown) — the
+ECMAScript-style grammar notation used by TSDoc and by cssdoc's own doc-comment spec
+(`CssDoc.grammarkdown`). It highlights productions, the `:` / `::` / `:::` separators, backtick
+terminals, `<character-class>` tokens, `U+` code points, parameter and constraint brackets, and the
+`but not` / `one of` / `lookahead` / `empty` keywords.
+
+## Use with Shiki or VitePress
+
+The default export is a Shiki `LanguageRegistration`, so it registers directly:
+
+```ts
+// .vitepress/config.ts
+import grammarkdown from "@cssdoc/grammarkdown-tmlanguage";
+
+export default {
+  markdown: {
+    languages: [grammarkdown],
+  },
+};
+```
+
+Then tag fenced blocks with `grammarkdown`.
+
+## Use the raw grammar
+
+For editors or other TextMate consumers, the grammar is published as a plain file:
+
+```js
+import grammar from "@cssdoc/grammarkdown-tmlanguage/grammarkdown.tmLanguage.json" with { type: "json" };
+```
+
+Its scope name is `source.grammarkdown`.

package/dist/index.d.mts

@@ -0,0 +1,193 @@
+//#region grammarkdown.tmLanguage.json.d.ts
+declare let $schema: string;
+declare let name: string;
+declare let scopeName: string;
+declare let fileTypes: string[];
+declare let patterns: {
+  include: string;
+}[];
+declare namespace repository {
+  namespace comment {
+    export let match: string;
+    let name_1: string;
+    export { name_1 as name };
+  }
+  namespace prose {
+    let match_1: string;
+    export { match_1 as match };
+    let name_2: string;
+    export { name_2 as name };
+  }
+  namespace directive {
+    let match_2: string;
+    export { match_2 as match };
+    let name_3: string;
+    export { name_3 as name };
+  }
+  namespace production {
+    let match_3: string;
+    export { match_3 as match };
+    export let captures: {
+      "1": {
+        name: string;
+      };
+      "2": {
+        name: string;
+        patterns: {
+          include: string;
+        }[];
+      };
+      "3": {
+        name: string;
+      };
+    };
+  }
+  namespace constraint {
+    export let begin: string;
+    export let end: string;
+    let name_4: string;
+    export { name_4 as name };
+    let patterns_1: ({
+      include: string;
+      match?: undefined;
+      name?: undefined;
+    } | {
+      match: string;
+      name: string;
+      include?: undefined;
+    })[];
+    export { patterns_1 as patterns };
+  }
+  namespace terminal {
+    let match_4: string;
+    export { match_4 as match };
+    let name_5: string;
+    export { name_5 as name };
+  }
+  namespace characterClass {
+    let match_5: string;
+    export { match_5 as match };
+    let name_6: string;
+    export { name_6 as name };
+  }
+  namespace codepoint {
+    let match_6: string;
+    export { match_6 as match };
+    let name_7: string;
+    export { name_7 as name };
+  }
+  namespace keywords {
+    let match_7: string;
+    export { match_7 as match };
+    let name_8: string;
+    export { name_8 as name };
+  }
+  namespace optional {
+    let match_8: string;
+    export { match_8 as match };
+    let name_9: string;
+    export { name_9 as name };
+  }
+  namespace nonterminal {
+    let match_9: string;
+    export { match_9 as match };
+    let name_10: string;
+    export { name_10 as name };
+  }
+  namespace parameters {
+    let match_10: string;
+    export { match_10 as match };
+    let name_11: string;
+    export { name_11 as name };
+  }
+}
+declare namespace __json_default_export {
+  export { $schema, name, scopeName, fileTypes, patterns, repository };
+}
+//#endregion
+//#region src/index.d.ts
+/** The grammarkdown TextMate grammar, shaped as a Shiki `LanguageRegistration`. */
+declare const grammarkdown: {
+  $schema: string;
+  name: string;
+  scopeName: string;
+  fileTypes: string[];
+  patterns: {
+    include: string;
+  }[];
+  repository: {
+    comment: {
+      match: string;
+      name: string;
+    };
+    prose: {
+      match: string;
+      name: string;
+    };
+    directive: {
+      match: string;
+      name: string;
+    };
+    production: {
+      match: string;
+      captures: {
+        "1": {
+          name: string;
+        };
+        "2": {
+          name: string;
+          patterns: {
+            include: string;
+          }[];
+        };
+        "3": {
+          name: string;
+        };
+      };
+    };
+    constraint: {
+      begin: string;
+      end: string;
+      name: string;
+      patterns: ({
+        include: string;
+        match?: undefined;
+        name?: undefined;
+      } | {
+        match: string;
+        name: string;
+        include?: undefined;
+      })[];
+    };
+    terminal: {
+      match: string;
+      name: string;
+    };
+    characterClass: {
+      match: string;
+      name: string;
+    };
+    codepoint: {
+      match: string;
+      name: string;
+    };
+    keywords: {
+      match: string;
+      name: string;
+    };
+    optional: {
+      match: string;
+      name: string;
+    };
+    nonterminal: {
+      match: string;
+      name: string;
+    };
+    parameters: {
+      match: string;
+      name: string;
+    };
+  };
+};
+//#endregion
+export { __json_default_export as default, grammarkdown };

package/dist/index.mjs

@@ -0,0 +1,118 @@
+//#region grammarkdown.tmLanguage.json
+var grammarkdown_tmLanguage_default = {
+	$schema: "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+	name: "grammarkdown",
+	scopeName: "source.grammarkdown",
+	fileTypes: ["grammarkdown"],
+	patterns: [
+		{ "include": "#comment" },
+		{ "include": "#prose" },
+		{ "include": "#directive" },
+		{ "include": "#production" },
+		{ "include": "#constraint" },
+		{ "include": "#terminal" },
+		{ "include": "#characterClass" },
+		{ "include": "#codepoint" },
+		{ "include": "#keywords" },
+		{ "include": "#optional" },
+		{ "include": "#nonterminal" }
+	],
+	repository: {
+		"comment": {
+			"match": "//.*$",
+			"name": "comment.line.double-slash.grammarkdown"
+		},
+		"prose": {
+			"match": "^\\s*>.*$",
+			"name": "string.unquoted.prose.grammarkdown"
+		},
+		"directive": {
+			"match": "@(import|define|line|augments|noStrictParametricRedeclaration|noSyntacticPredicates)\\b",
+			"name": "keyword.control.directive.grammarkdown"
+		},
+		"production": {
+			"match": "^\\s*([A-Za-z][A-Za-z0-9]*)\\s*(\\[[^\\]]*\\])?\\s*(:::|::|:)",
+			"captures": {
+				"1": { "name": "entity.name.type.production.grammarkdown" },
+				"2": {
+					"name": "meta.parameter-list.grammarkdown",
+					"patterns": [{ "include": "#parameters" }]
+				},
+				"3": { "name": "keyword.operator.definition.grammarkdown" }
+			}
+		},
+		"constraint": {
+			"begin": "\\[",
+			"end": "\\]",
+			"name": "meta.annotation.grammarkdown",
+			"patterns": [
+				{ "include": "#keywords" },
+				{ "include": "#terminal" },
+				{
+					"match": "[+~?]",
+					"name": "keyword.operator.parameter.grammarkdown"
+				},
+				{
+					"match": "[∈∉≠]|!=",
+					"name": "keyword.operator.assertion.grammarkdown"
+				},
+				{
+					"match": "\\b[A-Za-z][A-Za-z0-9]*\\b",
+					"name": "variable.parameter.grammarkdown"
+				}
+			]
+		},
+		"terminal": {
+			"match": "`[^`]*`",
+			"name": "constant.character.terminal.grammarkdown"
+		},
+		"characterClass": {
+			"match": "<[^>\\n]+>",
+			"name": "constant.language.character-class.grammarkdown"
+		},
+		"codepoint": {
+			"match": "\\bU\\+[0-9A-Fa-f]{2,6}\\b",
+			"name": "constant.numeric.codepoint.grammarkdown"
+		},
+		"keywords": {
+			"match": "\\b(but\\s+not|one\\s+of|lookahead|empty|here|but|not|or|of|no)\\b",
+			"name": "keyword.control.grammarkdown"
+		},
+		"optional": {
+			"match": "\\?",
+			"name": "keyword.operator.optional.grammarkdown"
+		},
+		"nonterminal": {
+			"match": "\\b[A-Z][A-Za-z0-9]*\\b",
+			"name": "variable.other.nonterminal.grammarkdown"
+		},
+		"parameters": {
+			"match": "\\b[A-Za-z][A-Za-z0-9]*\\b",
+			"name": "variable.parameter.grammarkdown"
+		}
+	}
+};
+//#endregion
+//#region src/index.ts
+/**
+* `@cssdoc/grammarkdown-tmlanguage` — a TextMate grammar for
+* [grammarkdown](https://github.com/rbuckton/grammarkdown), the ECMAScript-style grammar notation used
+* by TSDoc and by cssdoc's own doc-comment spec. The default export is the grammar as a Shiki
+* `LanguageRegistration` (it carries `name` and `scopeName`), so it drops straight into a Shiki or
+* VitePress config; the raw grammar is also published at `./grammarkdown.tmLanguage.json` for editors
+* and other TextMate consumers.
+*
+* @example
+* ```ts
+* // .vitepress/config.ts
+* import grammarkdown from "@cssdoc/grammarkdown-tmlanguage";
+* export default { markdown: { languages: [grammarkdown] } };
+* ```
+*
+* @module @cssdoc/grammarkdown-tmlanguage
+*/
+/** The grammarkdown TextMate grammar, shaped as a Shiki `LanguageRegistration`. */
+const grammarkdown = grammarkdown_tmLanguage_default;
+var src_default = grammarkdown_tmLanguage_default;
+//#endregion
+export { src_default as default, grammarkdown };

package/grammarkdown.tmLanguage.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "grammarkdown",
+  "scopeName": "source.grammarkdown",
+  "fileTypes": ["grammarkdown"],
+  "patterns": [
+    { "include": "#comment" },
+    { "include": "#prose" },
+    { "include": "#directive" },
+    { "include": "#production" },
+    { "include": "#constraint" },
+    { "include": "#terminal" },
+    { "include": "#characterClass" },
+    { "include": "#codepoint" },
+    { "include": "#keywords" },
+    { "include": "#optional" },
+    { "include": "#nonterminal" }
+  ],
+  "repository": {
+    "comment": {
+      "match": "//.*$",
+      "name": "comment.line.double-slash.grammarkdown"
+    },
+    "prose": {
+      "match": "^\\s*>.*$",
+      "name": "string.unquoted.prose.grammarkdown"
+    },
+    "directive": {
+      "match": "@(import|define|line|augments|noStrictParametricRedeclaration|noSyntacticPredicates)\\b",
+      "name": "keyword.control.directive.grammarkdown"
+    },
+    "production": {
+      "match": "^\\s*([A-Za-z][A-Za-z0-9]*)\\s*(\\[[^\\]]*\\])?\\s*(:::|::|:)",
+      "captures": {
+        "1": { "name": "entity.name.type.production.grammarkdown" },
+        "2": {
+          "name": "meta.parameter-list.grammarkdown",
+          "patterns": [{ "include": "#parameters" }]
+        },
+        "3": { "name": "keyword.operator.definition.grammarkdown" }
+      }
+    },
+    "constraint": {
+      "begin": "\\[",
+      "end": "\\]",
+      "name": "meta.annotation.grammarkdown",
+      "patterns": [
+        { "include": "#keywords" },
+        { "include": "#terminal" },
+        { "match": "[+~?]", "name": "keyword.operator.parameter.grammarkdown" },
+        { "match": "[∈∉≠]|!=", "name": "keyword.operator.assertion.grammarkdown" },
+        { "match": "\\b[A-Za-z][A-Za-z0-9]*\\b", "name": "variable.parameter.grammarkdown" }
+      ]
+    },
+    "terminal": {
+      "match": "`[^`]*`",
+      "name": "constant.character.terminal.grammarkdown"
+    },
+    "characterClass": {
+      "match": "<[^>\\n]+>",
+      "name": "constant.language.character-class.grammarkdown"
+    },
+    "codepoint": {
+      "match": "\\bU\\+[0-9A-Fa-f]{2,6}\\b",
+      "name": "constant.numeric.codepoint.grammarkdown"
+    },
+    "keywords": {
+      "match": "\\b(but\\s+not|one\\s+of|lookahead|empty|here|but|not|or|of|no)\\b",
+      "name": "keyword.control.grammarkdown"
+    },
+    "optional": {
+      "match": "\\?",
+      "name": "keyword.operator.optional.grammarkdown"
+    },
+    "nonterminal": {
+      "match": "\\b[A-Z][A-Za-z0-9]*\\b",
+      "name": "variable.other.nonterminal.grammarkdown"
+    },
+    "parameters": {
+      "match": "\\b[A-Za-z][A-Za-z0-9]*\\b",
+      "name": "variable.parameter.grammarkdown"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cssdoc/grammarkdown-tmlanguage",
+  "version": "0.1.0",
+  "description": "A TextMate grammar for grammarkdown (the ECMAScript-style grammar notation), shipped as a Shiki language.",
+  "keywords": [
+    "grammar",
+    "grammarkdown",
+    "shiki",
+    "syntax-highlighting",
+    "textmate",
+    "tmlanguage"
+  ],
+  "homepage": "https://cssdoc.dev",
+  "bugs": "https://github.com/thedannywahl/cssdoc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/cssdoc.git",
+    "directory": "syntaxes/grammarkdown"
+  },
+  "files": [
+    "dist",
+    "grammarkdown.tmLanguage.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./grammarkdown.tmLanguage.json": "./grammarkdown.tmLanguage.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "4.1.9",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "publint": "publint"
+  }
+}