{"id":21442081,"url":"https://github.com/norskeld/shikigami","last_synced_at":"2025-07-14T17:32:40.864Z","repository":{"id":49839284,"uuid":"444937717","full_name":"norskeld/shikigami","owner":"norskeld","description":"Opinionated syntax highlighting with shiki for markdown-it.","archived":false,"fork":false,"pushed_at":"2024-04-16T11:35:15.000Z","size":1027,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-13T10:52:54.738Z","etag":null,"topics":["hacktoberfest","markdown","markdown-it","markdown-it-plugin","shiki","syntax-highlighting","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/norskeld.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2022-01-05T20:14:18.000Z","updated_at":"2022-09-30T20:26:05.000Z","dependencies_parsed_at":"2024-04-16T12:41:22.068Z","dependency_job_id":"e9ca27be-71a4-4240-9fb9-082f208a1ab0","html_url":"https://github.com/norskeld/shikigami","commit_stats":{"total_commits":45,"total_committers":2,"mean_commits":22.5,"dds":"0.19999999999999996","last_synced_commit":"0468daf0b7d5546ef6b489d8e127b9c3e4bb1ccd"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":"norskeld/serpent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norskeld%2Fshikigami","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norskeld%2Fshikigami/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norskeld%2Fshikigami/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norskeld%2Fshikigami/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/norskeld","download_url":"https://codeload.github.com/norskeld/shikigami/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225990484,"owners_count":17556153,"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":["hacktoberfest","markdown","markdown-it","markdown-it-plugin","shiki","syntax-highlighting","typescript"],"created_at":"2024-11-23T01:48:31.841Z","updated_at":"2024-11-23T01:48:32.233Z","avatar_url":"https://github.com/norskeld.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `式神` shikigami\n\n[![Build/Test](https://img.shields.io/github/actions/workflow/status/norskeld/shikigami/test.yml?style=flat-square\u0026colorA=22272d\u0026colorB=22272d)](https://github.com/norskeld/shikigami/actions 'Build and test workflows')\n[![Coverage](https://img.shields.io/coverallsCoverage/github/norskeld/shikigami?style=flat-square\u0026colorA=22272d\u0026colorB=22272d)](https://coveralls.io/github/norskeld/shikigami 'Test coverage')\n[![NPM](https://img.shields.io/npm/v/@nrsk/shikigami?style=flat-square\u0026colorA=22272d\u0026colorB=22272d)](https://npm.im/@nrsk/shikigami 'This package on NPM')\n![Supported Node Versions](https://img.shields.io/node/v/%40nrsk/shikigami?style=flat-square\u0026colorA=22272d\u0026colorB=22272d)\n[![Semantic Release](https://img.shields.io/static/v1?label=semantic+release\u0026message=✔\u0026style=flat-square\u0026colorA=22272d\u0026colorB=22272d)](https://github.com/semantic-release/semantic-release 'This package uses semantic release to handle releasing, versioning, changelog generation and tagging')\n\nOpinionated syntax highlighting with [shiki] for [markdown-it].\n\n![Example of rendered code](/assets/shikigami.png)\n\n## Installation\n\nJust use your favorite package manager.\n\n```bash\nnpm i @nrsk/shikigami\n```\n\nThis package comes both in **CommonJS** and **ESM** flavors. No additional steps required, just `import` or `require` it.\n\n## Usage\n\n\u003e [!NOTE]\\\n\u003e No styles provided by default, so you need to style everything yourself, using classes described below. There's an [example of CSS here][css-example] using Tailwind.\n\n\u003e [!WARNING]\\\n\u003e Most likely this plugin is incompatible with other plugins that process fenced code blocks, e.g. **[markdown-it-attrs]**, which can be used to assign classes to elements and has similar syntax.\n\nThis package exposes a function named **shikigami**, which is a `Promise`, that resolves to a **markdown-it** plugin function. Hence, you must `await` it (or use `.then` syntax), and only then pass the resulting function to **markdown-it**.\n\nBelow is an example of usage.\n\n```typescript\nimport { shikigami, loadTheme } from '@nrsk/shikigami'\nimport md from 'markdown-it'\n\nasync function processMarkdown(input) {\n  const parser = md('commonmark').use(\n    await shikigami({\n      withLanguage: true,\n      withLineNumbers: true,\n      highlightInvert: true,\n      highlighter: {\n        // All other shiki's highlighter options are available as well,\n        // so you can load additional languages and so on.\n        theme: await loadTheme('./theme/custom.json')\n      }\n    })\n  )\n\n  return parser.render(input)\n}\n```\n\n## Markdown syntax\n\nThis plugin introduces a simple syntax extension for fenced code blocks, that allows you to change plugin options in-place. Options defined this way have precedence over plugin options.\n\n````markdown\n# Example\n\n```typescript {{ \u003coption\u003e: \u003cvalue\u003e, \u003coption\u003e: \u003cvalue\u003e, ... }}\ninterface User {\n  id: number\n  firstName: string\n  lastName: string\n  role: string\n}\n```\n````\n\n## Options\n\nList of options that can be passed to `shikigami` function. Options allowed to be used directly in Markdown through syntax extension are marked accordingly.\n\n### `openToken?: string`\n\n- **Default**: `{{`\n- **Allowed in Markdown**: no\n\nUse this option to change the opening token for extended Markdown syntax.\n\n### `closeToken?: string`\n\n- **Default**: `}}`\n- **Allowed in Markdown**: no\n\nUse this option to change the closing token for extended Markdown syntax.\n\n### `withLanguage?: boolean`\n\n- **Default**: `false`\n- **Allowed in Markdown**: yes\n\nSet to `true` to allow rendering a sibling `\u003cdiv\u003e` with a `language-\u003clanguageId\u003e` class. This is useful when you want to show the language specified in your fenced code block.\n\n### `withLineNumbers?: boolean`\n\n- **Default**: `false`\n- **Allowed in Markdown**: yes\n\nSet to `true` to render line numbers.\n\n### `highlight?: Array\u003cnumber | Array\u003cnumber\u003e\u003e`\n\n- **Default**: `[]`\n- **Allowed in Markdown**: yes\n\nUse this option to specify which lines or ranges of lines should be marked with specified highlighting class (or classes). These classes can be customized via `highlightClasses` and `highlightRangeClasses` options.\n\n#### Examples\n\n- Highlight lines **5** and **7**:\n\n  ```\n  {{ highlight: [5, 7] }}\n  ```\n\n- Highlight lines **5**, **7**, and lines in range from **10** to **15**:\n\n  ```\n  {{ highlight: [5, 7, [10, 15]] }}\n  ```\n\n### `highlightClasses?: Array\u003cstring\u003e`\n\n- **Default**: `['highlight']`\n- **Allowed in Markdown**: no\n\nUse this option to customize classes for highlighted lines.\n\n### `highlightRangeClasses?: HighlightRangeClasses`\n\n- **Default**: `['highlight-start', 'highlight-inner', 'highlight-end']`\n- **Allowed in Markdown**: no\n\nUse this option to customize classes for highlighted ranges. Must be a tuple of exactly three elements.\n\n#### Explanation\n\n- The first class is assigned to the first line of a range.\n- The second class is assigned to all lines between the first and the last line of a range. _This only applied if the range covers 3 and more lines._\n- The third class is assigned to the last line of a range.\n\n_Is this overkill? Probably..._\n\n### `highlightInvert?: boolean`\n\n- **Default**: `false`\n- **Allowed in Markdown**: yes\n\nSet to `true` to allow marking lines that are not highlighted with specified classes. These classes can be customised via `highlightInvertClasses`.\n\n**Note: this will work only if `highlight` option is set to a non-empty array of lines.**\n\n### `highlightInvertClasses?: Array\u003cstring\u003e`\n\n- **Default**: `['highlight-invert']`\n- **Allowed in Markdown**: no\n\nUse this option to customize classes for unhighlighted lines.\n\n### `highlighter?: HighlighterOptions`\n\n- **Default**: `{}`\n- **Allowed in Markdown**: no\n\nHighlighter options which will be passed right into shiki's `getHighlighter`. See [shiki documentation][shiki-docs] for available options.\n\n## API\n\nBesides exposing the `shikigami` function, this plugin re-exports shiki's `loadTheme` just for convenience.\n\n### `shikigami(userOptions?: ShikigamiOptions): Promise\u003cPluginSimple\u003e`\n\nPlugin factory function that resolves to a **markdown-it** plugin.\n\n```typescript\nimport { shikigami } from '@nrsk/shikigami'\nimport anchor from 'markdown-it-anchor'\nimport md from 'markdown-it'\n\nasync function processMarkdown(input) {\n  return md('commonmark')\n    .use(\n      await shikigami({\n        /** Plugin options. */\n      })\n    )\n    .use(anchor)\n    .render(input)\n}\n```\n\n### `loadTheme(themePath: string): Promise\u003cIShikiTheme\u003e`\n\nShiki's theme loader.\n\n## Todo\n\n- [ ] Tests.\n- [ ] Diffs support.\n\n## License\n\n[MIT](LICENSE).\n\n\u003c!-- Links. --\u003e\n\n[shiki]: https://shiki.matsu.io\n[markdown-it]: https://github.com/markdown-it/markdown-it\n[markdown-it-attrs]: https://github.com/arve0/markdown-it-attrs\n[shiki-docs]: https://shiki.matsu.io\n[css-example]: https://github.com/norskeld/vm.codes/blob/207e1759247861bbb0ab252827832e20f3760b5d/src/components/Content.astro#L20-L186\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorskeld%2Fshikigami","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorskeld%2Fshikigami","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorskeld%2Fshikigami/lists"}