{"id":14979476,"url":"https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter","last_synced_at":"2025-07-22T19:03:34.959Z","repository":{"id":61357711,"uuid":"541874234","full_name":"andrewtbiehl/kramdown-syntax_tree_sitter","owner":"andrewtbiehl","description":"Syntax highlight code with Tree-sitter via Kramdown.","archived":false,"fork":false,"pushed_at":"2024-12-06T22:13:15.000Z","size":577,"stargazers_count":21,"open_issues_count":12,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T04:51:17.324Z","etag":null,"topics":["jekyll","kramdown","plugin","ruby","rust","syntax-highlighting"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewtbiehl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-27T02:43:48.000Z","updated_at":"2025-01-11T03:16:53.000Z","dependencies_parsed_at":"2024-05-01T05:30:08.023Z","dependency_job_id":"e1b6ff92-3752-41dd-b467-292b8fb2b3a3","html_url":"https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter","commit_stats":{"total_commits":460,"total_committers":2,"mean_commits":230.0,"dds":"0.32173913043478264","last_synced_commit":"dac06f9a94c70f3d22333b7479bedd3ada354e81"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/andrewtbiehl/kramdown-syntax_tree_sitter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewtbiehl%2Fkramdown-syntax_tree_sitter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewtbiehl%2Fkramdown-syntax_tree_sitter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewtbiehl%2Fkramdown-syntax_tree_sitter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewtbiehl%2Fkramdown-syntax_tree_sitter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewtbiehl","download_url":"https://codeload.github.com/andrewtbiehl/kramdown-syntax_tree_sitter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewtbiehl%2Fkramdown-syntax_tree_sitter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266553959,"owners_count":23947240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jekyll","kramdown","plugin","ruby","rust","syntax-highlighting"],"created_at":"2024-09-24T14:00:05.222Z","updated_at":"2025-07-22T19:03:34.929Z","avatar_url":"https://github.com/andrewtbiehl.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kramdown Tree-sitter Highlighter\n\n[![Build status](https://img.shields.io/github/actions/workflow/status/andrewtbiehl/kramdown-syntax_tree_sitter/quality-control.yml?branch=main\u0026style=flat-square\u0026logo=github)](https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter/actions/workflows/quality-control.yml)\n[![RubyGems page](https://img.shields.io/gem/v/kramdown-syntax_tree_sitter?style=flat-square\u0026color=blue\u0026logo=rubygems\u0026logoColor=white)](https://rubygems.org/gems/kramdown-syntax_tree_sitter)\n\n***Syntax highlight code with [Tree-sitter](https://tree-sitter.github.io/tree-sitter)\nvia [Kramdown](https://kramdown.gettalong.org).***\n\nThis is a syntax highlighter plugin for [Kramdown](https://kramdown.gettalong.org) that\nleverages\n[Tree-sitter's native syntax highlighter](https://tree-sitter.github.io/tree-sitter/syntax-highlighting)\nto highlight code blocks (and spans) when rendering HTML.\n\n## Getting started\n\n### Requirements and compatibility\n\nThis plugin is built for [Kramdown](https://kramdown.gettalong.org) and hence requires a\ncompatible [Ruby](https://www.ruby-lang.org) installation to function. It is also\nessentially an adapter for the\n[Tree-sitter highlight library](https://crates.io/crates/tree-sitter-highlight) and\nhence also requires a compatible [Rust](https://www.rust-lang.org) installation to\nfunction. It is officially compatible with the following environments:\n\n- **Ruby**: 3.0, 3.1, 3.2, 3.3\n- **Rust**: 1.76, 1.77, 1.78, 1.79\n- **Platforms**: MacOS, Linux\n\n### Installation\n\nFor projects using [Bundler](https://bundler.io) for dependency management, run the\nfollowing command to both install the gem and add it to the Gemfile:\n\n```shell\nbundle add kramdown-syntax_tree_sitter\n```\n\nOtherwise, install the gem via the following command:\n\n```shell\ngem install kramdown-syntax_tree_sitter\n```\n\n## Usage\n\n### Quickstart\n\nFor the following example to function, the\n[Tree-sitter Python parser library](https://github.com/tree-sitter/tree-sitter-python)\nmust be present inside a directory called `tree_sitter_parsers`, which in turn must be\nlocated in the home directory. See the subsequent\n['Tree-sitter parsers'](#tree-sitter-parsers) section for more information.\n\n```ruby\nrequire 'kramdown'\nrequire 'kramdown/syntax_tree_sitter'\n\ntext = \u003c\u003c~MARKDOWN\n  ~~~python\n  print('Hello, World!')\n  ~~~\nMARKDOWN\n\nKramdown::Document.new(text, syntax_highlighter: :'tree-sitter').to_html\n```\n\n### General usage\n\nTo successfully highlight input text via Kramdown with this plugin enabled, make sure\nthat every language referenced has a corresponding Tree-sitter parser library installed.\nSee the subsequent ['Language identifiers'](#language-identifiers) and\n['Tree-sitter parsers'](#tree-sitter-parsers) sections for more information.\n\n### Usage with Jekyll\n\nThis plugin can be used with the popular static site generator\n[Jekyll](https://jekyllrb.com). Jekyll projects using Kramdown for Markdown rendering\n(the default setting for Jekyll), can enable this plugin by installing the gem (most\nlikely via Bundler, as described in the ['Installation'](#installation) section) and\nthen adding the following lines to the Jekyll project's configuration file\n(`_config.yml`):\n\n```yaml\nplugins:\n  - kramdown/syntax_tree_sitter\n  # Other Jekyll plugins...\nkramdown:\n  syntax_highlighter: tree-sitter\n  # Other Kramdown options...\n```\n\nNote that this plugin's general usage prerequisites (described in the previous\n['General usage'](#general-usage) section) still apply when using this plugin with\nJekyll.\n\nAlso, there are multiple ways to render highlighted code blocks with Jekyll, as\nillustrated in the following table:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eMethod name\u003c/th\u003e\n\u003cth\u003eExample\u003c/th\u003e\n\u003cth\u003eSupported by this plugin\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eFenced code block\u003c/td\u003e\n\u003ctd\u003e\n\n---\n````\n```python\nprint('Hello, World!')\n```\n\nor\n\n~~~python\nprint('Hello, World!')\n~~~\n````\n---\n\n\u003c/td\u003e\n\u003ctd\u003e:white_check_mark:\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eIndented code block\u003c/td\u003e\n\u003ctd\u003e\n\n---\n```\n    print('Hello, World!')\n{: class=\"language-python\" }\n```\n---\n\n\u003c/td\u003e\n\u003ctd\u003e:white_check_mark:\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eLiquid highlight tag\u003c/td\u003e\n\u003ctd\u003e\n\n---\n```\n{% highlight python %}\nprint('Hello, World!')\n{% endhighlight %}\n```\n---\n\n\u003c/td\u003e\n\u003ctd\u003e:x:\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nSince Jekyll does not defer to Kramdown to render Liquid highlight tags, this plugin\ndoes not support highlighting code using that method. Therefore, ***code blocks must be\nrepresented in either fenced or indented notation*** in order to be rendered via this\nplugin.\n\n### Tree-sitter parsers\n\nTree-sitter relies on external parser libraries to understand each language grammar.\nThus, in order to syntax highlight a given language using this plugin, that language's\nTree-sitter parser library must be installed to the correct directory on your machine.\nThis directory is set as `~/tree_sitter_parsers` by default but is also configurable\n(see the ['Configuration'](#configuration) section for details).\n\nFor most such parser libraries, installation simply amounts to downloading the\nrepository into the configured Tree-sitter parsers directory.\n\nA partial list of languages for which Tree-sitter parser libraries have been developed\ncan be found on\n[the official Tree-sitter website](https://tree-sitter.github.io/tree-sitter/#available-parsers).\n\n### Language identifiers\n\nFor most popular languages, this plugin recognizes the same language identifiers as used\nby the popular highlighter [Rouge](https://github.com/rouge-ruby/rouge). For example,\nboth 'python' and 'py' may be used to identify a code block written in Python. For the\ncomplete list of Rouge language identifiers recognized by this plugin, see\n[`lib/kramdown/syntax_tree_sitter/languages.rb`](https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter/blob/main/lib/kramdown/syntax_tree_sitter/languages.rb).\n\nThis plugin also automatically supports the language identifier format used by\nTree-sitter, known as as the 'scope' name. For example, the scope name for Python is\n'source.python', whereas for HTML it is 'text.html.basic'.\n\nFor any identifiers currently supported by Rouge but not by this plugin, feel free to\nopen an issue or pull request on GitHub to have them included.\n\n### CSS styling\n\nCode highlights can be rendered either via inline CSS styles or via CSS classes, which\nare applied to each token in the parsed code.\n\nTo use CSS classes for highlighting, set the `css_classes` Kramdown syntax-highlighting\noption to `true`. Otherwise, the plugin will apply highlights via inline CSS styles.\n\nThe inline CSS styles are derived from Tree-sitter's built-in default highlighting\ntheme, repeated here for convenience:\n\n| Token name | CSS style |\n| :-- | :-- |\n| attribute | `color: #af0000; font-style: italic;` |\n| comment | `color: #8a8a8a; font-style: italic;` |\n| constant | `color: #875f00;` |\n| function | `color: o#005fd7;` |\n| function.builtin | `color: #005fd7; font-weight: bold;` |\n| keyword | `color: #5f00d7;` |\n| operator | `color: #4e4e4e; font-weight: bold;` |\n| property | `color: #af0000;` |\n| string | `color: #008700;` |\n| string.special | `color: #008787;` |\n| tag | `color: #000087;` |\n| type | `color: #005f5f;` |\n| type.builtin | `color: #005f5f; font-weight: bold;` |\n| variable.builtin | `font-weight: bold;` |\n| variable.parameter | `text-decoration: underline;` |\n| constant.builtin, number | `color: #875f00; font-weight: bold;` |\n| constructor, module | `color: #af8700;` |\n| punctuation.bracket, punctuation.delimiter | `color: #4e4e4e;` |\n\nAny and all token types not represented in this default theme are consequently not\nhighlighted when using the inline CSS styles option.\n\nThe CSS class names are derived directly from Tree-sitter token names by replacing all\nfull stops ('.') with dashes ('-') and adding the prefix 'ts-'. For example, the CSS\nclass for 'function.builtin' tokens is 'ts-function-builtin'. The use of CSS classes\nallows for customization of highlighting styles, including the ability to highlight more\ntoken types than with the default inline CSS method. Of course, this also requires that\nan externally created CSS stylesheet defining the style for each token type is provided\nwhenever the Kramdown-generated HTML is rendered.\n\n### Configuration\n\nThis Kramdown plugin currently supports the following options when provided as sub-keys\nof the Kramdown option `syntax_highlighter_opts`:\n\n| Key | Description | Type | Default value |\n| :-- | :-- | :-- | :-- |\n| `tree_sitter_parsers_dir` | The path to the Tree-sitter language parsers directory. | String | `~/tree_sitter_parsers` |\n| `css_classes` | Whether to use CSS classes for highlights. | Boolean | `false` |\n\n## Contributing\n\nContributions are welcome!\n\n### Development\n\nTo set up a compatible local development environment, please first refer to the\n['Requirements and Compatibility'](#requirements-and-compatibility) section of this\ndocument.\n\nThis project also depends on Git submodules to run some of its tests. Accordingly, make\nsure to initialize recursive submodules when cloning the project for development\npurposes, for example with the following command:\n\n```shell\ngit clone --recurse-submodules https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter.git\n```\n\nAfter checking out the project, run `bundle install` from within it to install\ndependencies. Then run `bundle exec rake --tasks` to list all available Rake tasks. Each\ntask can be invoked via `bundle exec rake \u003ctask name\u003e`. For example,\n`bundle exec rake test` runs unit tests and `bundle exec rake smoke_test` installs the\ngem and runs a smoke test against it.\n\nThis project uses [GitHub Actions](https://github.com/features/actions) workflows to\nfacilitate continuous integration. The 'Quality Control' workflow runs any time new\ncommits are pushed to GitHub on any branch. This workflow runs the `rubocop`, `test`,\nand `smoke_test` Rake tasks to verify that new changes meet the project's code quality\nstandards, so it is strongly recommended that these tasks are first run locally against\nnew changes before such changes are pushed.\n\nThe 'Unreleased' section of the changelog should also be updated accordingly whenever\nsignificant changes are introduced.\n\n#### Release process\n\n1. Determine the new version number based on the changes being introduced. This project\n   follows the [Semantic Versioning](https://semver.org/spec/v2.0.0.html) versioning\n   standard.\n\n1. Make a commit to the trunk branch with the following changes:\n\n   - Update the project's version number (located in\n     [`lib/kramdown/syntax_tree_sitter/version.rb`](https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter/blob/main/lib/kramdown/syntax_tree_sitter/version.rb)).\n\n   - Update the project's changelog\n     ([`CHANGELOG.md`](https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter/blob/main/CHANGELOG.md))\n     with documentation for the new\n     version by modifying the current 'Unreleased' section accordingly.\n\n   - Add a copy of the following release template to the top of the changelog and update\n     the 'Unreleased' section link to restart the process for the next release.\n\n     ```markdown\n     ## [Unreleased]\n\n     ### Added\n     \u003c!-- For new features --\u003e\n\n     ### Changed\n     \u003c!-- For changes in existing functionality --\u003e\n\n     ### Deprecated\n     \u003c!-- For soon-to-be removed features --\u003e\n\n     ### Removed\n     \u003c!-- For now removed features --\u003e\n\n     ### Fixed\n     \u003c!-- For any bug fixes --\u003e\n\n     ### Security\n     \u003c!-- In case of vulnerabilities --\u003e\n     ```\n\n1. [Draft and publish a new GitHub release](https://github.com/andrewtbiehl/kramdown-syntax_tree_sitter/releases/new)\n   with a new trunk branch tag and title corresponding to the new version number and a\n   description copied over from the changelog. This will trigger the 'Gem Publication'\n   GitHub Actions workflow, which will push the new version to\n   [RubyGems.org](https://rubygems.org).\n\n## About\n\n[Tree-sitter](https://tree-sitter.github.io/tree-sitter) is a modern, general-purpose\nparsing library that outclasses many existing tools at the task of syntax highlighting.\nThis plugin adapts Tree-sitter's native highlighter for\n[Kramdown](https://kramdown.gettalong.org), so that Tree-sitter's superior highlighting\ncapabilities can be easily leveraged in the context of rendering Markdown.\n\nThe basic functionality of this plugin was originally presented as a blog post:\n*[\"Syntax highlight your Jekyll site with Tree-sitter!\"](https://andrewtbiehl.com/blog/jekyll-tree-sitter)*.\nThis article explains the original use case and inspiration for the project, walks\nthrough its implementation, and even provides some fun examples of syntax highlighting\nwith Tree-sitter.\n\n### Disclaimer\n\nNeither this plugin nor its author are affiliated with Tree-sitter or Kramdown in any\nway. For any information particular to\n[Tree-sitter](https://tree-sitter.github.io/tree-sitter) or\n[Kramdown](https://kramdown.gettalong.org), please refer to their respective\ndocumentation directly.\n\n## License\n\nThis project is released under the MIT License.\n\nThe text for this license can be found in [the project's LICENSE.txt file](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewtbiehl%2Fkramdown-syntax_tree_sitter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewtbiehl%2Fkramdown-syntax_tree_sitter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewtbiehl%2Fkramdown-syntax_tree_sitter/lists"}