tm-grammars / tm-themes

Collection of TextMate grammars and themes, converted to JSON and re-distributed as npm packages. Extracted from Shiki, available for general usage.

Packages are automatically updated and published every day (if there are changes).

Preview Playground

Contribute

• Add a new grammar
• Add a new theme
• Fix a grammar or theme

Add a new grammar

[!NOTE] For new grammars to be accepted, we typically require the language to be popular and have a significant number of users. Usually we see GitHub's linguist repo as a marker for this. If you language is not in linguist, we would recommend adding it there first.

Meanwhile, to use a grammar with Shiki, you can always provide a custom grammar locally.

1. Fork this repository.
2. Install dependencies with pnpm install.
3. Add grammar source and metadata to sources-grammars.ts.
4. Add a code sample file <id>.sample for your language under ./samples. A sample should include a variety of language syntaxes and succinctly capture the idiosyncrasy of a language. Format requirements:

• Space for indentation.
• Less than 100 columns if possible.
• A comment with a link to the source on the last line (e.g. # From https://poignant.guide/book/chapter-5.html).

5. Generate a personal access token with the default permissions. This token is used to query public information from GitHub API and avoid rate limits.
6. Create a .env file and paste your generated token into the file like so:

GITHUB_TOKEN=your-personal-access-token

7. Run pnpm run fetch to download the grammar.
8. Run pnpm run play to start the playground. Select the new grammar in the left column to verify the accuracy and confirm that the grammar works as expected.
9. Send in the PR!

Add a new theme

[!NOTE] For new themes to be accepted, we typically require the theme to be popular and have a significant number of users. Like over 50K downloads on VS Code marketplace, or over 300 stars on GitHub.

Meanwhile, to use a theme with Shiki, you can always provide a custom theme locally.

1. Fork this repository.
2. Install dependencies with pnpm install.
3. Add theme source and metadata to sources-themes.ts.
4. Generate a personal access token with the default permissions. This token is used to query public information from GitHub API and avoid rate limits.
5. Create a .env file and paste your generated token into the file like so:

GITHUB_TOKEN=your-personal-access-token

6. Run pnpm run fetch to download the theme.
7. Run pnpm run play to start the playground. Select the new theme in the right column to verify the accuracy and confirm that the theme works as expected.
8. Send in the PR!

Fix a grammar or theme

We don't maintain the grammars and themes in this repository. This repository only normalizes the grammars and themes from their original repositories and re-distributes them as npm packages. If you want to fix a grammar or theme, you should submit a PR to the original repository.

You can find the original repository and source file locations in sources-grammars.ts and sources-themes.ts.

After upstream PR is merged, this repository will be automatically synced and updated.

License

The grammars and themes included in this package are covered by their repositories’ respective licenses, which are permissive (apache-2.0, mit, etc), and made available in Grammars NOTICE and Themes NOTICE.

All other files MIT © Pine Wu & Anthony Fu.