# SuperCollider Pygments lexer plugin
This is a Pygments lexer with custom styles for SuperCollider code. It provides syntax highlighting for SuperCollider files in Pygments-supported environments like mkdocs, sphinx, LaTeX's minted package, and more.
Pygments has a built-in lexer for SuperCollider, but the existing implementation has many issues such as not recognizing class names, incorrectly highlighting words which are not keywords in SuperCollider, etc. This plugin is a full reimplementation with much improved lexing, which means more accurate syntax highlighting of SuperCollider code. It has been submitted to the Pygments project and is awaiting review, but in the meantime, you can use it with this plugin.
## Features
- **Accurate lexer**: Recognizes SuperCollider class names, keywords, symbols, and general syntax
- **Custom color themes**: Includes both light and dark themes designed specifically for SuperCollider code
- **Easy integration**: Works with Pygments-based tools such as mkdocs, Sphinx, and LaTeX minted
## Important: Language/lexer name
**Due to a naming conflict with Pygments' built-in SuperCollider lexer, you must use `sc-plugin` as the language/lexer name wherever you want to use this plugin.**
Do **not** use `sc` or `supercollider`, as those will use the built-in lexer.
## Installation
Install the plugin using pip:
```shell
pip install pygments-supercollider-lexer
```
## Usage
### 1. Python
In vanilla Python scripts, you can use the lexer like this:
```python
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter
code = '''
SynthDef(\sine, {
var sig = SinOsc.ar(\freq.kr(440), 0, \amp.kr(0.1));
Out.ar(0, sig ! 2);
}).add;
'''
lexer = get_lexer_by_name('sc-plugin')
formatter = HtmlFormatter(style='supercollider_dark') # or 'supercollider_light'
result = highlight(code, lexer, formatter)
with open("output.html", "w") as f:
f.write(result)
```
Or on the command line:
```shell
pygmentize -l sc-plugin -O style=supercollider_dark -f html myfile.scd > output.html
```
### 2. Markdown/mkdocs
To use this lexer in markdown files with mkdocs, you need to install the [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) and configure your `mkdocs.yml` file to include the `pymdownx.highlight` extension as well as the `pymdownx.superfences` extension.
```yaml
markdown_extensions:
- pymdownx.highlight
- pymdownx.superfences
```
Then, specify `sc-plugin` as the language name at the top of your code block:
````markdown
```sc-plugin
{ SinOsc.ar(440) * 0.1 }.play;
```
````
#### Using the supplied styles with mkdocs
To use the custom SuperCollider color themes that come with this plugin in a site built with mkdocs, the best solution is to generate CSS rules for the chosen style and include it in your project. Pygments makes it easy to generate CSS files for the styles with the `pygmentize` command:
```shell
# For dark theme
pygmentize -S supercollider_dark -f html -a .highlight > css/supercollider_dark.css
# For light theme
pygmentize -S supercollider_light -f html -a .highlight > css/supercollider_light.css
```
Then, include the generated CSS files in your `mkdocs.yml`:
```yaml
extra_css:
- css/supercollider_dark.css
```
If you want to support both light and dark modes, you can include both CSS files and wrap their contents in corresponding [prefers-color-scheme media query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme).
If using the [Material for MkDocs theme](https://squidfunk.github.io/mkdocs-material/) to switch between light and dark modes, you can use `[data-md-color-scheme="default"]` as a selector for the light theme and `[data-md-color-scheme="slate"]` for the dark theme.
### 3. LaTeX minted
To use the lexer with the minted package in LaTeX:
```latex
\usepackage{minted}
...
\begin{minted}{sc-plugin}
// SuperCollider code here
(
SynthDef(\sine, {
Out.ar(0, SinOsc.ar(440))
}).add;
)
\end{minted}
```
## Troubleshooting
- If you see incorrect highlighting, double-check that you are using `sc-plugin` as the language/lexer name.
- If you get "no lexer for alias" errors, ensure the plugin is installed in the same Python environment as your tool (MkDocs, Sphinx, etc).
- If you update the plugin, reinstall it with `pip install -e .` to refresh the entry points.
## Development
To contribute or modify the lexer, (fork and) clone the repository and install it in editable mode:
```shell
git clone https://github.com/aeskildsen/pygments-supercollider-lexer.git
cd pygments-supercollider-lexer
pip install -e .[dev]
```
Run tests with:
```shell
pytest
```
## License
This plugin is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pygments-supercollider-lexer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pygments, supercollider, syntax highlighting",
"author": "Anders Eskildsen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3b/7f/b52db8666dcdae7c47ef1360d4202b9c3ae66d41a89f5cde765fb3c88033/pygments_supercollider_lexer-0.1.1.tar.gz",
"platform": null,
"description": "# SuperCollider Pygments lexer plugin\n\nThis is a Pygments lexer with custom styles for SuperCollider code. It provides syntax highlighting for SuperCollider files in Pygments-supported environments like mkdocs, sphinx, LaTeX's minted package, and more.\n\nPygments has a built-in lexer for SuperCollider, but the existing implementation has many issues such as not recognizing class names, incorrectly highlighting words which are not keywords in SuperCollider, etc. This plugin is a full reimplementation with much improved lexing, which means more accurate syntax highlighting of SuperCollider code. It has been submitted to the Pygments project and is awaiting review, but in the meantime, you can use it with this plugin.\n\n## Features\n\n- **Accurate lexer**: Recognizes SuperCollider class names, keywords, symbols, and general syntax\n- **Custom color themes**: Includes both light and dark themes designed specifically for SuperCollider code\n- **Easy integration**: Works with Pygments-based tools such as mkdocs, Sphinx, and LaTeX minted\n\n## Important: Language/lexer name\n\n**Due to a naming conflict with Pygments' built-in SuperCollider lexer, you must use `sc-plugin` as the language/lexer name wherever you want to use this plugin.** \n\nDo **not** use `sc` or `supercollider`, as those will use the built-in lexer.\n\n## Installation\n\nInstall the plugin using pip:\n\n```shell\npip install pygments-supercollider-lexer\n```\n\n## Usage\n\n### 1. Python\n\nIn vanilla Python scripts, you can use the lexer like this:\n\n```python\nfrom pygments import highlight\nfrom pygments.lexers import get_lexer_by_name\nfrom pygments.formatters import HtmlFormatter\n\ncode = '''\nSynthDef(\\sine, {\n var sig = SinOsc.ar(\\freq.kr(440), 0, \\amp.kr(0.1));\n Out.ar(0, sig ! 2);\n}).add;\n'''\n\nlexer = get_lexer_by_name('sc-plugin')\nformatter = HtmlFormatter(style='supercollider_dark') # or 'supercollider_light'\nresult = highlight(code, lexer, formatter)\n\nwith open(\"output.html\", \"w\") as f:\n f.write(result)\n```\n\nOr on the command line:\n\n```shell\npygmentize -l sc-plugin -O style=supercollider_dark -f html myfile.scd > output.html\n```\n\n### 2. Markdown/mkdocs\n\nTo use this lexer in markdown files with mkdocs, you need to install the [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) and configure your `mkdocs.yml` file to include the `pymdownx.highlight` extension as well as the `pymdownx.superfences` extension.\n\n```yaml\nmarkdown_extensions:\n - pymdownx.highlight\n - pymdownx.superfences\n```\n\nThen, specify `sc-plugin` as the language name at the top of your code block:\n\n````markdown\n```sc-plugin\n{ SinOsc.ar(440) * 0.1 }.play;\n```\n````\n\n#### Using the supplied styles with mkdocs\n\nTo use the custom SuperCollider color themes that come with this plugin in a site built with mkdocs, the best solution is to generate CSS rules for the chosen style and include it in your project. Pygments makes it easy to generate CSS files for the styles with the `pygmentize` command:\n\n```shell\n# For dark theme\npygmentize -S supercollider_dark -f html -a .highlight > css/supercollider_dark.css\n\n# For light theme \npygmentize -S supercollider_light -f html -a .highlight > css/supercollider_light.css\n```\n\nThen, include the generated CSS files in your `mkdocs.yml`:\n\n```yaml\nextra_css:\n - css/supercollider_dark.css\n```\n\nIf you want to support both light and dark modes, you can include both CSS files and wrap their contents in corresponding [prefers-color-scheme media query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme).\n\nIf using the [Material for MkDocs theme](https://squidfunk.github.io/mkdocs-material/) to switch between light and dark modes, you can use `[data-md-color-scheme=\"default\"]` as a selector for the light theme and `[data-md-color-scheme=\"slate\"]` for the dark theme.\n\n### 3. LaTeX minted\n\nTo use the lexer with the minted package in LaTeX:\n```latex\n\\usepackage{minted}\n...\n\\begin{minted}{sc-plugin}\n// SuperCollider code here\n(\nSynthDef(\\sine, {\n Out.ar(0, SinOsc.ar(440))\n}).add;\n)\n\\end{minted}\n```\n\n## Troubleshooting\n\n- If you see incorrect highlighting, double-check that you are using `sc-plugin` as the language/lexer name.\n- If you get \"no lexer for alias\" errors, ensure the plugin is installed in the same Python environment as your tool (MkDocs, Sphinx, etc).\n- If you update the plugin, reinstall it with `pip install -e .` to refresh the entry points.\n\n## Development\n\nTo contribute or modify the lexer, (fork and) clone the repository and install it in editable mode:\n\n```shell\ngit clone https://github.com/aeskildsen/pygments-supercollider-lexer.git\ncd pygments-supercollider-lexer\npip install -e .[dev]\n```\n\nRun tests with:\n\n```shell\npytest\n```\n\n## License\n\nThis plugin is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.",
"bugtrack_url": null,
"license": null,
"summary": "A Pygments lexer for SuperCollider",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/aeskildsen/pygments-supercollider-lexer",
"Issues": "https://github.com/aeskildsen/pygments-supercollider-lexer/issues",
"Repository": "https://github.com/aeskildsen/pygments-supercollider-lexer"
},
"split_keywords": [
"pygments",
" supercollider",
" syntax highlighting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f8eda2852cb34b5aadb79db4d0baa50ded0c473b782f12aeb6eb6281d63d8bfe",
"md5": "c95e4f46186a538c747c0008944f01c0",
"sha256": "001098b18a8c169b10439fa9410318f20557cc925766c20ee2f3015b6545dd2f"
},
"downloads": -1,
"filename": "pygments_supercollider_lexer-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c95e4f46186a538c747c0008944f01c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16830,
"upload_time": "2025-08-26T07:48:52",
"upload_time_iso_8601": "2025-08-26T07:48:52.735889Z",
"url": "https://files.pythonhosted.org/packages/f8/ed/a2852cb34b5aadb79db4d0baa50ded0c473b782f12aeb6eb6281d63d8bfe/pygments_supercollider_lexer-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3b7fb52db8666dcdae7c47ef1360d4202b9c3ae66d41a89f5cde765fb3c88033",
"md5": "a27ab687abdd02940f4d42d6271d8a2c",
"sha256": "19711e7a597e65cbfc18aac39a8314ccb95c6abd8390bb4b81195ebf17cb141a"
},
"downloads": -1,
"filename": "pygments_supercollider_lexer-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "a27ab687abdd02940f4d42d6271d8a2c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8153,
"upload_time": "2025-08-26T07:48:54",
"upload_time_iso_8601": "2025-08-26T07:48:54.060889Z",
"url": "https://files.pythonhosted.org/packages/3b/7f/b52db8666dcdae7c47ef1360d4202b9c3ae66d41a89f5cde765fb3c88033/pygments_supercollider_lexer-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 07:48:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aeskildsen",
"github_project": "pygments-supercollider-lexer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pygments-supercollider-lexer"
}
JSON
