Linguist 语法高亮索引Grammar Index全解析查询、排查与维护指南【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist本文围绕 Linguist 仓库中的 vendor/README.mdGrammar index展开说明这份语法索引是什么、如何读懂它、遇到语法高亮错误时如何定位上报以及它背后由 script/list-grammars、grammars.yml 与 vendor/grammars 子模块构成的自动生成与同步机制。读完你将掌握快速定位某一语言语法来源的方法、 标记的真实含义以及向 Linguist 提交新语法高亮支持的完整流程。Grammar Index 是什么Linguist 是 GitHub 用来识别仓库语言并生成语言统计、语法高亮的工具。其中语法高亮这一能力并不由 Linguist 自己实现而是从外部挑选一系列语法定义Grammar交给 GitHub 前端渲染时使用。vendor/README.md 就是这份挑选结果的公开索引它以- **语言名:** 语法来源的列表形式逐条列出了 Linguist 当前为每一种受支持语言所选择的语法包以及该语法包的维护仓库。文档开头的定位很明确This is a list of grammars that Linguist selects to provide syntax highlighting on GitHub.也就是说这份索引是 GitHub 语法高亮功能的供货清单——每一种能被正确高亮的语言都能在这里找到其语法来源。读懂索引格式一行一条映射索引的每一行结构固定- **语言名:** 语法仓库维护方例如- **Ruby:** tree-sitter/tree-sitter-ruby - **Python:** tree-sitter/tree-sitter-python - **Shell:** atom/language-shellscript - **XML:** textmate/xml.tmbundle每个条目回答两个问题语言名GitHub 上显示的编程语言名称与 lib/linguist/languages.yml 中的语言定义对应语法来源提供该语言语法定义的上游仓库通常是 TextMate Bundle、Sublime/Atom 语法包或 tree-sitter 语法库。索引末尾覆盖了大量小众语言与数据格式如1C Enterprise、B (Formal Method)、CoNLL-U、Omgrofl、TSPLIB data等完整条目见 vendor/README.md 本体。 标记的含义上游滞后提示索引中有相当一部分条目带有 标记例如C、C#、Go、HTML、Java、JavaScript、PHP、Python、Ruby、Rust、TypeScript、Swift、Nix、Elixir、Gleam、TLA、Regular Expression等。文档对此有明确说明grammars marked with are not updated when Linguist is so upstream fixes may take longer to appear on GitHub.翻译过来即带 的语法不会跟随 Linguist 的发布节奏同步更新。Linguist 发布时可能没有重新拉取这些语法的最新版本因此即使上游仓库修复了 bug修复在 GitHub 上的生效时间也会更晚。从条目内容可以观察到一个规律几乎所有带 的语法都来自 tree-sitter 官方组织如 vendor/grammars 中对应的tree-sitter-*子模块。这可以推断Linguist 对 tree-sitter 系语法采用了与 TextMate Bundle 系不同的更新策略——前者按独立节奏跟进后者随 Linguist 发布同步更新。如果你发现某个 语法的高亮问题需要明确即使上游已修复也要等待 Linguist 下一次同步这些语法子模块。遇到高亮错误如何排查与上报文档给出了明确的上报路径If youve encountered an error with highlighting, please find the grammar in the list below and report it to the appropriate repository.即遇到高亮错误时不要直接找 Linguist而是在 vendor/README.md 的索引中找到对应语言条目确认该语言使用的语法来源是哪家仓库维护的语法去那个仓库提交 issue并附上复现用的代码片段。例如一个 Markdown 高亮问题索引显示其语法来源为wooorm/markdown-tm-language则问题应上报到该仓库而如果问题涉及 Python 高亮则应上报到tree-sitter/tree-sitter-python同时注意它是 条目修复生效存在延迟。判断该找谁还有一种辅助手段索引条目中语法来源的名称大多与 vendor/grammars 下的子模块目录名一一对应如tree-sitter-c、xml.tmbundle、MagicPython等可直接在本地查看对应语法定义文件。索引背后的自动生成机制这份索引不是手写的。文档在列表前有一行关键注释Everything below this line is auto-generated by script/list-grammars. Manual edits will be lost即列表以下全部由 script/list-grammars 自动生成手动修改会被覆盖。与之配套的数据源是根目录下的 grammars.yml它的结构是把 vendor/grammars 下的子模块目录映射到 TextMate scope 名称vendor/grammars/AL: - source.al vendor/grammars/Alloy.tmbundle: - source.alloy vendor/grammars/MagicPython: - source.python - source.python.console - source.python.traceback这个机制在测试中有严格保障。test/test_grammars.rb 中test_readme_file_is_in_sync会对比vendor/README.md与script/list-grammars --print的输出def test_readme_file_is_in_sync current_data File.read(#{ROOT}/vendor/README.md).to_s.sub(/\A.?!--.?--\n/mu, ) updated_data script/list-grammars --print assert_equal current_data, updated_data, Grammar list is out-of-date. Run script/list-grammars end一旦新增语法后忘记重新生成索引CI 会直接失败并提示运行script/list-grammars。这保证了索引、grammars.yml 与 vendor/grammars 子模块三者永远保持一致。同一测试文件还验证了其他一致性约束test_no_duplicate_scopesgrammars.yml 中不能出现重复的 scopetest_submodules_are_in_syncgrammars.yml 中列出的子模块必须真实存在于仓库反之仓库中新增的子模块也必须登记到 grammars.ymltest_submodules_use_https_links.gitmodules 中的子模块地址必须是 HTTPS 而非 SSH。语法包的组织形式vendor/grammars 子模块所有被选中的语法包都作为git 子模块存放在 vendor/grammars当前包含 555 个目录每个子模块对应一个语法来源。之所以用子模块而非直接拷贝代码是因为语法包通常由社区在独立仓库维护子模块能保留其版本与提交历史Linguist 可以通过更新子模块引用来升级语法而无需改动自身代码grammars.yml 以子模块路径为 key 登记 scope形成子模块 → scope的完整索引。初次克隆仓库后需要执行 script/bootstrap 来初始化这些子模块其核心步骤包括git submodule init git submodule sync --quiet script/fast-submodule-updatefast-submodule-update是 Linguist 对子模块拉取的加速封装避免逐个 clone 造成超时。语法包实际加载路径由 lib/linguist/grammars.rb 提供module Linguist module Grammars # Get the path to the directory containing the language grammar JSON files. def self.path File.expand_path(../../../grammars, __FILE__) end end end它指向编译产物grammars/目录——运行时使用的是由 script/grammar-compiler 把各子模块的.tmLanguage/tree-sitter定义编译成的 JSON 文件而不是直接解析原始语法包。如何新增一种语言的语法高亮如果你为 Linguist 支持的语言提供或修复了语法需要通过官方脚本 script/add-grammar 把它登记为子模块。该脚本用法# 基本用法添加新语法子模块 script/add-grammar https://example.com/owner/repo # 替换已有语法子模块 script/add-grammar --replace old-module-name https://example.com/owner/new-repo # 静默模式失败时才输出 script/add-grammar -q https://example.com/owner/repo关键参数说明参数作用url位置参数语法仓库地址必填-q, --quiet不打印过程信息仅在失败时输出-r, --replace SUBMODULE替换已有的语法子模块例如用新维护者仓库替换旧仓库-h, --help打印完整帮助信息添加完成后还需保证索引同步完整流程为运行script/add-grammar url添加/替换子模块更新 grammars.yml登记新子模块路径及其 TextMate scope运行script/list-grammars重新生成 vendor/README.md 中的索引列表提交后由 CI 中的 test/test_grammars.rb 校验三处一致性README 同步、子模块同步、scope 无重复。语言与语法来源对照代表性样例下表从 vendor/README.md 摘录代表性条目展示主流语言分别由哪类语法来源提供完整清单以文档本体及 grammars.yml 为准语言语法来源类型是否 C / C / Objective-CTextMate C Bundle 系C 是 C 否C# / Uno / EQdotnet/csharp-tmLanguageC# 是 Go / Java / JavaScript / Python / Ruby / Rust / TypeScript / Swift / HTML / CSS / PHP / Nix / Elixir / Gleamtree-sitter 官方语法库全部 Shell / Gentoo Ebuild / OpenRC runscriptatom/language-shellscript否XML / XSLT / XProc / Web Ontology Languagetextmate/xml.tmbundle否Perl / R / Tcl / Pascal / Fortran / TeXTextMate 官方 Bundle否JSON / Max / Jupyter NotebookNovaGrammars否ABAP / COBOL / JCL社区语言服务器配套语法否可以看出 条目集中在 tree-sitter 官方语法而 TextMate Bundle 系语法随 Linguist 发布同步更新这正是为什么有些语法修复快、有些慢的根源。小结一条从查询到维护的完整链路理解这份 Grammar Index 后你可以按需走完以下链路查在 vendor/README.md 中按语言名检索语法来源报高亮出错时按索引指向的上游仓库提交 issue并留意 条目的延迟生效问题核本地通过 vendor/grammars 子模块与 grammars.yml 核对 scope 映射增/改用 script/add-grammar 登记新语法运行 script/list-grammars 重新生成索引并保证通过 test/test_grammars.rb 的一致性校验。整条链路以子模块存储、YAML 登记、脚本生成、测试锁定的方式运转使得数百种语言的语法高亮来源既高度可追溯又能长期保持自动同步。【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Linguist 语法高亮索引（Grammar Index）全解析：查询、排查与维护指南
Linguist 语法高亮索引Grammar Index全解析查询、排查与维护指南【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist本文围绕 Linguist 仓库中的 vendor/README.mdGrammar index展开说明这份语法索引是什么、如何读懂它、遇到语法高亮错误时如何定位上报以及它背后由 script/list-grammars、grammars.yml 与 vendor/grammars 子模块构成的自动生成与同步机制。读完你将掌握快速定位某一语言语法来源的方法、 标记的真实含义以及向 Linguist 提交新语法高亮支持的完整流程。Grammar Index 是什么Linguist 是 GitHub 用来识别仓库语言并生成语言统计、语法高亮的工具。其中语法高亮这一能力并不由 Linguist 自己实现而是从外部挑选一系列语法定义Grammar交给 GitHub 前端渲染时使用。vendor/README.md 就是这份挑选结果的公开索引它以- **语言名:** 语法来源的列表形式逐条列出了 Linguist 当前为每一种受支持语言所选择的语法包以及该语法包的维护仓库。文档开头的定位很明确This is a list of grammars that Linguist selects to provide syntax highlighting on GitHub.也就是说这份索引是 GitHub 语法高亮功能的供货清单——每一种能被正确高亮的语言都能在这里找到其语法来源。读懂索引格式一行一条映射索引的每一行结构固定- **语言名:** 语法仓库维护方例如- **Ruby:** tree-sitter/tree-sitter-ruby - **Python:** tree-sitter/tree-sitter-python - **Shell:** atom/language-shellscript - **XML:** textmate/xml.tmbundle每个条目回答两个问题语言名GitHub 上显示的编程语言名称与 lib/linguist/languages.yml 中的语言定义对应语法来源提供该语言语法定义的上游仓库通常是 TextMate Bundle、Sublime/Atom 语法包或 tree-sitter 语法库。索引末尾覆盖了大量小众语言与数据格式如1C Enterprise、B (Formal Method)、CoNLL-U、Omgrofl、TSPLIB data等完整条目见 vendor/README.md 本体。 标记的含义上游滞后提示索引中有相当一部分条目带有 标记例如C、C#、Go、HTML、Java、JavaScript、PHP、Python、Ruby、Rust、TypeScript、Swift、Nix、Elixir、Gleam、TLA、Regular Expression等。文档对此有明确说明grammars marked with are not updated when Linguist is so upstream fixes may take longer to appear on GitHub.翻译过来即带 的语法不会跟随 Linguist 的发布节奏同步更新。Linguist 发布时可能没有重新拉取这些语法的最新版本因此即使上游仓库修复了 bug修复在 GitHub 上的生效时间也会更晚。从条目内容可以观察到一个规律几乎所有带 的语法都来自 tree-sitter 官方组织如 vendor/grammars 中对应的tree-sitter-*子模块。这可以推断Linguist 对 tree-sitter 系语法采用了与 TextMate Bundle 系不同的更新策略——前者按独立节奏跟进后者随 Linguist 发布同步更新。如果你发现某个 语法的高亮问题需要明确即使上游已修复也要等待 Linguist 下一次同步这些语法子模块。遇到高亮错误如何排查与上报文档给出了明确的上报路径If youve encountered an error with highlighting, please find the grammar in the list below and report it to the appropriate repository.即遇到高亮错误时不要直接找 Linguist而是在 vendor/README.md 的索引中找到对应语言条目确认该语言使用的语法来源是哪家仓库维护的语法去那个仓库提交 issue并附上复现用的代码片段。例如一个 Markdown 高亮问题索引显示其语法来源为wooorm/markdown-tm-language则问题应上报到该仓库而如果问题涉及 Python 高亮则应上报到tree-sitter/tree-sitter-python同时注意它是 条目修复生效存在延迟。判断该找谁还有一种辅助手段索引条目中语法来源的名称大多与 vendor/grammars 下的子模块目录名一一对应如tree-sitter-c、xml.tmbundle、MagicPython等可直接在本地查看对应语法定义文件。索引背后的自动生成机制这份索引不是手写的。文档在列表前有一行关键注释Everything below this line is auto-generated by script/list-grammars. Manual edits will be lost即列表以下全部由 script/list-grammars 自动生成手动修改会被覆盖。与之配套的数据源是根目录下的 grammars.yml它的结构是把 vendor/grammars 下的子模块目录映射到 TextMate scope 名称vendor/grammars/AL: - source.al vendor/grammars/Alloy.tmbundle: - source.alloy vendor/grammars/MagicPython: - source.python - source.python.console - source.python.traceback这个机制在测试中有严格保障。test/test_grammars.rb 中test_readme_file_is_in_sync会对比vendor/README.md与script/list-grammars --print的输出def test_readme_file_is_in_sync current_data File.read(#{ROOT}/vendor/README.md).to_s.sub(/\A.?!--.?--\n/mu, ) updated_data script/list-grammars --print assert_equal current_data, updated_data, Grammar list is out-of-date. Run script/list-grammars end一旦新增语法后忘记重新生成索引CI 会直接失败并提示运行script/list-grammars。这保证了索引、grammars.yml 与 vendor/grammars 子模块三者永远保持一致。同一测试文件还验证了其他一致性约束test_no_duplicate_scopesgrammars.yml 中不能出现重复的 scopetest_submodules_are_in_syncgrammars.yml 中列出的子模块必须真实存在于仓库反之仓库中新增的子模块也必须登记到 grammars.ymltest_submodules_use_https_links.gitmodules 中的子模块地址必须是 HTTPS 而非 SSH。语法包的组织形式vendor/grammars 子模块所有被选中的语法包都作为git 子模块存放在 vendor/grammars当前包含 555 个目录每个子模块对应一个语法来源。之所以用子模块而非直接拷贝代码是因为语法包通常由社区在独立仓库维护子模块能保留其版本与提交历史Linguist 可以通过更新子模块引用来升级语法而无需改动自身代码grammars.yml 以子模块路径为 key 登记 scope形成子模块 → scope的完整索引。初次克隆仓库后需要执行 script/bootstrap 来初始化这些子模块其核心步骤包括git submodule init git submodule sync --quiet script/fast-submodule-updatefast-submodule-update是 Linguist 对子模块拉取的加速封装避免逐个 clone 造成超时。语法包实际加载路径由 lib/linguist/grammars.rb 提供module Linguist module Grammars # Get the path to the directory containing the language grammar JSON files. def self.path File.expand_path(../../../grammars, __FILE__) end end end它指向编译产物grammars/目录——运行时使用的是由 script/grammar-compiler 把各子模块的.tmLanguage/tree-sitter定义编译成的 JSON 文件而不是直接解析原始语法包。如何新增一种语言的语法高亮如果你为 Linguist 支持的语言提供或修复了语法需要通过官方脚本 script/add-grammar 把它登记为子模块。该脚本用法# 基本用法添加新语法子模块 script/add-grammar https://example.com/owner/repo # 替换已有语法子模块 script/add-grammar --replace old-module-name https://example.com/owner/new-repo # 静默模式失败时才输出 script/add-grammar -q https://example.com/owner/repo关键参数说明参数作用url位置参数语法仓库地址必填-q, --quiet不打印过程信息仅在失败时输出-r, --replace SUBMODULE替换已有的语法子模块例如用新维护者仓库替换旧仓库-h, --help打印完整帮助信息添加完成后还需保证索引同步完整流程为运行script/add-grammar url添加/替换子模块更新 grammars.yml登记新子模块路径及其 TextMate scope运行script/list-grammars重新生成 vendor/README.md 中的索引列表提交后由 CI 中的 test/test_grammars.rb 校验三处一致性README 同步、子模块同步、scope 无重复。语言与语法来源对照代表性样例下表从 vendor/README.md 摘录代表性条目展示主流语言分别由哪类语法来源提供完整清单以文档本体及 grammars.yml 为准语言语法来源类型是否 C / C / Objective-CTextMate C Bundle 系C 是 C 否C# / Uno / EQdotnet/csharp-tmLanguageC# 是 Go / Java / JavaScript / Python / Ruby / Rust / TypeScript / Swift / HTML / CSS / PHP / Nix / Elixir / Gleamtree-sitter 官方语法库全部 Shell / Gentoo Ebuild / OpenRC runscriptatom/language-shellscript否XML / XSLT / XProc / Web Ontology Languagetextmate/xml.tmbundle否Perl / R / Tcl / Pascal / Fortran / TeXTextMate 官方 Bundle否JSON / Max / Jupyter NotebookNovaGrammars否ABAP / COBOL / JCL社区语言服务器配套语法否可以看出 条目集中在 tree-sitter 官方语法而 TextMate Bundle 系语法随 Linguist 发布同步更新这正是为什么有些语法修复快、有些慢的根源。小结一条从查询到维护的完整链路理解这份 Grammar Index 后你可以按需走完以下链路查在 vendor/README.md 中按语言名检索语法来源报高亮出错时按索引指向的上游仓库提交 issue并留意 条目的延迟生效问题核本地通过 vendor/grammars 子模块与 grammars.yml 核对 scope 映射增/改用 script/add-grammar 登记新语法运行 script/list-grammars 重新生成索引并保证通过 test/test_grammars.rb 的一致性校验。整条链路以子模块存储、YAML 登记、脚本生成、测试锁定的方式运转使得数百种语言的语法高亮来源既高度可追溯又能长期保持自动同步。【免费下载链接】linguistLanguage Savant. If your repositorys language is being reported incorrectly, send us a pull request!项目地址: https://gitcode.com/GitHub_Trending/li/linguist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考