{"id":25066784,"url":"https://github.com/trag1c/zig-codeblocks","last_synced_at":"2025-05-07T21:34:20.282Z","repository":{"id":275983713,"uuid":"927865846","full_name":"trag1c/zig-codeblocks","owner":"trag1c","description":"Zig ANSI syntax highlighting library for Python","archived":false,"fork":false,"pushed_at":"2025-04-25T20:23:46.000Z","size":783,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-05T00:56:26.663Z","etag":null,"topics":["ansi","discord","library","python","syntax-highlighting","zig"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/zig-codeblocks","language":"Rust","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/trag1c.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"trag1c"}},"created_at":"2025-02-05T17:10:38.000Z","updated_at":"2025-04-25T20:17:29.000Z","dependencies_parsed_at":"2025-03-18T02:27:42.298Z","dependency_job_id":"8624c5f2-0ec5-49a7-9b7c-f35038fb9a87","html_url":"https://github.com/trag1c/zig-codeblocks","commit_stats":null,"previous_names":["trag1c/zig-codeblocks"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trag1c%2Fzig-codeblocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trag1c%2Fzig-codeblocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trag1c%2Fzig-codeblocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trag1c%2Fzig-codeblocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trag1c","download_url":"https://codeload.github.com/trag1c/zig-codeblocks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252957768,"owners_count":21831548,"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","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":["ansi","discord","library","python","syntax-highlighting","zig"],"created_at":"2025-02-06T20:27:45.321Z","updated_at":"2025-05-07T21:34:20.258Z","avatar_url":"https://github.com/trag1c.png","language":"Rust","funding_links":["https://github.com/sponsors/trag1c"],"categories":[],"sub_categories":[],"readme":"[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n# zig-codeblocks\n\n`zig-codeblocks` is a Rust-powered CPython 3.9+ library for adding syntax\nhighlighting to Zig code blocks in Markdown files through ANSI escape codes.\nOriginally intended for patching the lack of syntax highlighting for Zig on\nDiscord.\n\n- [Installation](#installation)\n- [API Reference](#api-reference)\n  - [`extract_codeblocks`](#extract_codeblocks)\n  - [`highlight_zig_code`](#highlight_zig_code)\n  - [`process_markdown`](#process_markdown)\n  - [`CodeBlock`](#codeblock)\n  - [`Color`](#color)\n  - [`Style`](#style)\n  - [`Theme`](#theme)\n  - [`DEFAULT_THEME`](#default_theme)\n- [License](#license)\n\n## Installation\n`zig-codeblocks` is available on PyPI:\n```sh\npip install zig-codeblocks\n```\nYou can also install it from source:\n```sh\npip install git+https://github.com/trag1c/zig-codeblocks.git\n```\n---\n`zig-codeblocks` also exposes a CLI via a `cli` extra:\n```py\npip install \"zig-codeblocks[cli]\"\n```\nIf the CLI is all you need, you can run it with `uvx`:\n```sh\nuvx \"zig-codeblocks[cli]\" --help\n```\n\n\n## API Reference\n\n### `extract_codeblocks`\n```py\ndef extract_codeblocks(source: str | bytes) -\u003e list[CodeBlock]\n```\nYields [`CodeBlock`](#codeblock)s from a Markdown source.\nAssumes UTF-8 if source is `bytes`.\n\n**Example usage:**\n```py\nfrom pathlib import Path\n\nfrom zig_codeblocks import extract_codeblocks\n\nsource = Path(\"examples/riiz.md\").read_text()\nfor codeblock in extract_codeblocks(source):\n    print(f\"Language: {codeblock.lang}\")\n    print(f\"Body:\\n{codeblock.body}\")\n```\n```\nLanguage: py\nBody:\nprint(\"Hello, World!\")\n\nLanguage: zig\nBody:\nconst std = @import(\"std\");\npub fn main() !void {\n    std.debug.print(\"Hello, World!\\n\", .{});\n}\n```\n\n\n### `highlight_zig_code`\n```py\ndef highlight_zig_code(source: str | bytes, theme: Theme = DEFAULT_THEME) -\u003e str\n```\nReturns an ANSI syntax-highlighted version of the given Zig source code.\nAssumes UTF-8 if source is `bytes`.\nAn optional [`Theme`](#theme) can be supplied (defaults to\n[`DEFAULT_THEME`](#default_theme)).\n\n**Example usage:**\n```py\nfrom pathlib import Path\n\nfrom zig_codeblocks import DEFAULT_THEME, Color, Style, highlight_zig_code\n\nsource = Path(\"examples/hello_world.zig\").read_text()\n\ntheme = DEFAULT_THEME.copy()\ntheme[\"BuiltinIdentifier\"] = Style(Color.Orange, underline=True)\ntheme[\"String\"] = Style(Color.Cyan)\ndel theme[\"Type\"]\n\nprint(\n    highlight_zig_code(source),\n    highlight_zig_code(source, theme),\n    sep=\"\\n\\n\",\n)\n```\n\u003cimg src=\"examples/highlighted-zig-code.png\" width=\"65%\"\u003e\n\n\n### `process_markdown`\n```py\ndef process_markdown(\n    source: str | bytes,\n    theme: Theme = DEFAULT_THEME,\n    *,\n    only_code: bool = False,\n) -\u003e str\n```\nReturns a Markdown source with Zig code blocks syntax-highlighted.\nAssumes UTF-8 if source is `bytes`.\nAn optional [`Theme`](#theme) can be supplied (defaults to\n[`DEFAULT_THEME`](#default_theme)).\nIf `only_code` is True, only processed Zig code blocks will be returned.\n\n**Example usage:**\n```py\nfrom pathlib import Path\n\nfrom zig_codeblocks import process_markdown\n\nsource = Path(\"examples/riiz.md\").read_text()\nprint(process_markdown(source))\n```\n\u003cimg src=\"examples/processed-markdown.png\" width=\"85%\"\u003e\n\n\n### `CodeBlock`\n```py\nclass CodeBlock:\n    lang: str\n    body: str\n```\nA code block extracted from a Markdown source. Immutable.\n\n\n### `Color`\n```py\nclass Color(Enum):\n    Gray = \"30\"\n    Red = \"31\"\n    Green = \"32\"\n    Orange = \"33\"\n    Blue = \"34\"\n    Magenta = \"35\"\n    Cyan = \"36\"\n    White = \"37\"  # Black for light mode\n```\nAn enumeration of 3-bit ANSI colors.\nSome names were adjusted to match Discord's style.\nA color can be instantiated from a string too: `Color.from_string(\"Blue\")`.\n\n\n### `Style`\n```py\nclass Style:\n    color: Color\n    bold: bool = False\n    underline: bool = False\n```\nA style for syntax highlighting.\nTakes a [`Color`](#color) and can optionally be bold and/or underlined.\nImmutable.\nProduces an SGR sequence when converted to a string.\n\n\n### `Theme`\n```py\nclass Theme(TypedDict, total=False):\n    BuiltinIdentifier: Style\n    Call: Style\n    Comment: Style\n    Identifier: Style\n    Keyword: Style\n    Numeric: Style\n    PrimitiveValue: Style\n    String: Style\n    Type: Style\n```\nA theme dict for syntax highlighting Zig code.\nEach key is optional and can be provided a [`Style`](#style) to apply to the\ncorresponding token type.\nCan be instantiated with a dict literal or with a `Theme` call:\n```py\nfrom zig_codeblocks import Color, Style, Theme\n\ntheme_foo = Theme(\n    Numeric=Style(Color.Blue),\n    String=Style(Color.Green),\n)\n\ntheme_bar: Theme = {\n    \"Numeric\": Style(Color.Blue),\n    \"String\": Style(Color.Green),\n}\n\nassert theme_foo == theme_bar\n```\n\n\n### `DEFAULT_THEME`\nThe default theme used for highlighting, defined as follows:\n```py\nDEFAULT_THEME: Theme = {\n    \"BuiltinIdentifier\": Style(Color.Blue, bold=True),\n    \"Call\": Style(Color.Blue),\n    \"Comment\": Style(Color.Gray),\n    \"Keyword\": Style(Color.Magenta),\n    \"Numeric\": Style(Color.Cyan),\n    \"PrimitiveValue\": Style(Color.Cyan),\n    \"String\": Style(Color.Green),\n    \"Type\": Style(Color.Orange),\n}\n```\n\n\n## License\n`zig-codeblocks` is licensed under the [MIT License].  \n© [trag1c], 2025\n\n[MIT License]: https://opensource.org/license/mit/\n[trag1c]: https://github.com/trag1c/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrag1c%2Fzig-codeblocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrag1c%2Fzig-codeblocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrag1c%2Fzig-codeblocks/lists"}