From 7a5cd110f6a1f786d6b1f6d91f70e4bae7eccf30 Mon Sep 17 00:00:00 2001 From: Anthony Fu Date: Sun, 17 Dec 2023 10:54:12 +0100 Subject: [PATCH] docs: better langs and themes list --- docs/.vitepress/components/LanguagesList.vue | 51 ++++ docs/.vitepress/components/ThemesList.vue | 47 ++++ docs/.vitepress/config.ts | 12 +- docs/components.d.ts | 6 + docs/guide/load-lang.md | 84 ++++++ docs/guide/load-theme.md | 39 +++ docs/languages.md | 263 +------------------ docs/themes.md | 73 +---- packages/shikiji/scripts/prepare/themes.ts | 21 +- packages/shikiji/src/assets/themes.ts | 6 +- scripts/readme.ts | 40 --- 11 files changed, 249 insertions(+), 393 deletions(-) create mode 100644 docs/.vitepress/components/LanguagesList.vue create mode 100644 docs/.vitepress/components/ThemesList.vue create mode 100644 docs/guide/load-lang.md create mode 100644 docs/guide/load-theme.md delete mode 100644 scripts/readme.ts diff --git a/docs/.vitepress/components/LanguagesList.vue b/docs/.vitepress/components/LanguagesList.vue new file mode 100644 index 00000000..6577d675 --- /dev/null +++ b/docs/.vitepress/components/LanguagesList.vue @@ -0,0 +1,51 @@ + + + diff --git a/docs/.vitepress/components/ThemesList.vue b/docs/.vitepress/components/ThemesList.vue new file mode 100644 index 00000000..44ff1b72 --- /dev/null +++ b/docs/.vitepress/components/ThemesList.vue @@ -0,0 +1,47 @@ + + + diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 9dcc7e59..69cc5470 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -12,6 +12,8 @@ const GUIDES: DefaultTheme.NavItemWithLink[] = [ { text: 'Dual Themes', link: '/guide/dual-themes' }, { text: 'Transformers', link: '/guide/transformers' }, { text: 'Compat Build', link: '/guide/compat' }, + { text: 'Custom Themes', link: '/guide/load-theme' }, + { text: 'Custom Languages', link: '/guide/load-lang' }, ] const REFERENCES: DefaultTheme.NavItemWithLink[] = [ @@ -50,15 +52,7 @@ export default defineConfig({ codeTransformers: [ transformerTwoSlash({ explicitTrigger: true, - renderer: rendererRich({ - formatInfo(info) { - return info - .replace(/\<"abap".*?\>/, '') - .replace(/\<"abap".*\.\.\./, '...') - .replace(/\<"css-variables".*?\>/, '') - .replace(/\<"css-variables".*\.\.\./, '...') - }, - }), + renderer: rendererRich(), }), { // Render custom themes with codeblocks diff --git a/docs/components.d.ts b/docs/components.d.ts index 759ead5a..bd640329 100644 --- a/docs/components.d.ts +++ b/docs/components.d.ts @@ -8,8 +8,14 @@ export {} declare module 'vue' { export interface GlobalComponents { Badges: typeof import('./.vitepress/components/Badges.vue')['default'] + copy: typeof import('./.vitepress/components/LanguagesList copy.vue')['default'] + FunctionsList: typeof import('./.vitepress/components/FunctionsList.vue')['default'] + GrammarList: typeof import('./.vitepress/components/GrammarList.vue')['default'] HomeDemo: typeof import('./.vitepress/components/HomeDemo.vue')['default'] + LanguagesList: typeof import('./.vitepress/components/LanguagesList.vue')['default'] + LanugagesList: typeof import('./.vitepress/components/LanugagesList.vue')['default'] ShikijiMiniPlayground: typeof import('./.vitepress/components/ShikijiMiniPlayground.vue')['default'] ShikijiPlayground: typeof import('./.vitepress/components/ShikijiPlayground.vue')['default'] + ThemesList: typeof import('./.vitepress/components/ThemesList.vue')['default'] } } diff --git a/docs/guide/load-lang.md b/docs/guide/load-lang.md new file mode 100644 index 00000000..c476cb6f --- /dev/null +++ b/docs/guide/load-lang.md @@ -0,0 +1,84 @@ +# Load Custom Languages + +Check [All Builtin Languages](/languages) as well. + +You can load custom languages by passing a TextMate grammar object into the langs array. + +```ts +import { getHighlighter } from 'shikiji' + +const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8')) + +const highlighter = await getHighlighter({ + langs: [myLang] +}) + +const html = highlighter.codeToHtml(code, { + lang: 'my-lang', +}) +``` + +You can also load languages after the highlighter has been created. + +```ts +import { getHighlighter } from 'shikiji' + +const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8')) + +const highlighter = await getHighlighter() + +await highlighter.loadLanguage(myLang) // <-- + +const html = highlighter.codeToHtml(code, { + lang: 'my-lang', +}) +``` + +## Migrate from Shiki + +Since `shikiji` is environment agnostic, that means we don't have access to the file system. That means the `path` property `shiki` supports is not available in `shikiji`. Instead, you need to read them in yourself and pass the object. For example: + +```ts +const highlighter = await getHighlighter({ + langs: [ + { + name: 'vue-vine', + scopeName: 'source.vue-vine', + // ‼️ This would not work! + path: join(__dirname, './vine-ts.tmLanguage.json'), + embeddedLangs: [ + 'vue-html', + 'css', + 'scss', + 'sass', + 'less', + 'stylus', + ], + }, + ] +}) +``` + +Instead, load that file yourself (via `fs`, `import()`, `fetch()`, etc.) and pass the object: + +```ts +const vineGrammar = JSON.parse(fs.readFileSync(join(__dirname, './vine-ts.tmLanguage.json'), 'utf8')) + +const highlighter = await getHighlighter({ + langs: [ + { + name: 'vue-vine', + scopeName: 'source.vue-vine', + embeddedLangs: [ + 'vue-html', + 'css', + 'scss', + 'sass', + 'less', + 'stylus', + ], + ...vineGrammar + }, + ] +}) +``` diff --git a/docs/guide/load-theme.md b/docs/guide/load-theme.md new file mode 100644 index 00000000..0f5b36e2 --- /dev/null +++ b/docs/guide/load-theme.md @@ -0,0 +1,39 @@ +# Load Custom Themes + +Check [All Builtin Themes](/themes) as well. + +You can load custom themes by passing a `Theme` object into the themes array. + +```ts +import { getHighlighter } from 'shikiji' + +const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8')) + +const highlighter = await getHighlighter({ + themes: [myTheme] +}) + +const html = highlighter.codeToHtml(code, { + lang: 'javascript', + theme: 'my-theme' +}) +``` + +You can also load themes after the highlighter has been created. + +```ts +import { getHighlighter } from 'shikiji' + +const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8')) + +const highlighter = await getHighlighter() + +await highlighter.loadTheme(myTheme) // <-- + +const html = highlighter.codeToHtml(code, { + lang: 'javascript', + theme: 'my-theme' +}) +``` + +The theme should be a TextMate theme in JSON object. For example, [it should looks like this](https://github.com/antfu/vscode-theme-vitesse/blob/main/themes/vitesse-dark.json). diff --git a/docs/languages.md b/docs/languages.md index f34878f0..6ad5abf7 100644 --- a/docs/languages.md +++ b/docs/languages.md @@ -1,266 +1,7 @@ # Languages -## All Languages - Inherited from [`shiki`](https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki), here are all the languages bundled in `shikiji`. - -| ID | Name | Aliases | -| --- | --- | --- | -| `abap` | ABAP | | -| `actionscript-3` | ActionScript | | -| `ada` | Ada | | -| `apache` | Apache Conf | | -| `apex` | Apex | | -| `apl` | APL | | -| `applescript` | AppleScript | | -| `ara` | Ara | | -| `asm` | Assembly | | -| `astro` | Astro | | -| `awk` | AWK | | -| `ballerina` | Ballerina | | -| `bat` | Batch | `batch` | -| `beancount` | Beancount | | -| `berry` | Berry | `be` | -| `bibtex` | BibTeX | | -| `bicep` | Bicep | | -| `blade` | Blade | | -| `c` | C | | -| `cadence` | Cadence | `cdc` | -| `clarity` | Clarity | | -| `clojure` | Clojure | `clj` | -| `cmake` | CMake | | -| `cobol` | COBOL | | -| `codeql` | CodeQL | `ql` | -| `coffee` | CoffeeScript | | -| `cpp` | C++ | `c++` | -| `crystal` | Crystal | | -| `csharp` | C# | `c#`, `cs` | -| `css` | CSS | | -| `csv` | csv syntax | | -| `cue` | CUE | | -| `cypher` | Cypher | `cql` | -| `d` | D | | -| `dart` | Dart | | -| `dax` | DAX | | -| `diff` | Diff | | -| `docker` | Docker | `dockerfile` | -| `dream-maker` | Dream Maker | | -| `elixir` | Elixir | | -| `elm` | Elm | | -| `erb` | ERB | | -| `erlang` | Erlang | `erl` | -| `fish` | Fish | | -| `fsharp` | F# | `f#`, `fs` | -| `gdresource` | GDResource | | -| `gdscript` | GDScript | | -| `gdshader` | GDShader | | -| `gherkin` | Gherkin | | -| `git-commit` | Git Commit Message | | -| `git-rebase` | Git Rebase Message | | -| `glimmer-js` | Glimmer JS | `gjs` | -| `glimmer-ts` | Glimmer TS | `gts` | -| `glsl` | GLSL | | -| `gnuplot` | Gnuplot | | -| `go` | Go | | -| `graphql` | GraphQL | `gql` | -| `groovy` | Groovy | | -| `hack` | Hack | | -| `haml` | Ruby Haml | | -| `handlebars` | Handlebars | `hbs` | -| `haskell` | Haskell | `hs` | -| `hcl` | HashiCorp HCL | | -| `hjson` | Hjson | | -| `hlsl` | HLSL | | -| `html` | HTML | | -| `http` | HTTP | | -| `imba` | Imba | | -| `ini` | INI | `properties` | -| `java` | Java | | -| `javascript` | JavaScript | `js` | -| `jinja-html` | Jinja | | -| `jison` | Jison | | -| `json` | JSON | | -| `json5` | JSON5 | | -| `jsonc` | JSON with Comments | | -| `jsonl` | JSON Lines | | -| `jsonnet` | Jsonnet | | -| `jssm` | JSSM | `fsl` | -| `jsx` | JSX | | -| `julia` | Julia | | -| `kotlin` | Kotlin | `kt`, `kts` | -| `kusto` | Kusto | `kql` | -| `latex` | LaTeX | | -| `less` | Less | | -| `liquid` | Liquid | | -| `lisp` | Lisp | | -| `logo` | Logo | | -| `lua` | Lua | | -| `make` | Makefile | `makefile` | -| `markdown` | Markdown | `md` | -| `marko` | Marko | | -| `matlab` | MATLAB | | -| `mdc` | mdc | | -| `mdx` | MDX | | -| `mermaid` | Mermaid | | -| `mojo` | MagicPython | | -| `narrat` | Narrat Language | `nar` | -| `nextflow` | Nextflow | `nf` | -| `nginx` | Nginx | | -| `nim` | Nim | | -| `nix` | Nix | | -| `nushell` | nushell | `nu` | -| `objective-c` | Objective-C | `objc` | -| `objective-cpp` | Objective-C++ | | -| `ocaml` | OCaml | | -| `pascal` | Pascal | | -| `perl` | Perl | | -| `php` | PHP | | -| `plsql` | PL/SQL | | -| `postcss` | PostCSS | | -| `powerquery` | PowerQuery | | -| `powershell` | PowerShell | `ps`, `ps1` | -| `prisma` | Prisma | | -| `prolog` | Prolog | | -| `proto` | Protocol Buffer 3 | | -| `pug` | Pug | `jade` | -| `puppet` | Puppet | | -| `purescript` | PureScript | | -| `python` | Python | `py` | -| `r` | R | | -| `raku` | Raku | `perl6` | -| `razor` | ASP.NET Razor | | -| `reg` | Windows Registry Script | | -| `rel` | Rel | | -| `riscv` | RISC-V | | -| `rst` | reStructuredText | | -| `ruby` | Ruby | `rb` | -| `rust` | Rust | `rs` | -| `sas` | SAS | | -| `sass` | Sass | | -| `scala` | Scala | | -| `scheme` | Scheme | | -| `scss` | SCSS | | -| `shaderlab` | ShaderLab | `shader` | -| `shellscript` | Shell | `bash`, `sh`, `shell`, `zsh` | -| `shellsession` | Shell Session | `console` | -| `smalltalk` | Smalltalk | | -| `solidity` | Solidity | | -| `sparql` | SPARQL | | -| `splunk` | Splunk Query Language | `spl` | -| `sql` | SQL | | -| `ssh-config` | SSH Config | | -| `stata` | Stata | | -| `stylus` | Stylus | `styl` | -| `svelte` | Svelte | | -| `swift` | Swift | | -| `system-verilog` | SystemVerilog | | -| `tasl` | Tasl | | -| `tcl` | Tcl | | -| `tex` | TeX | | -| `toml` | TOML | | -| `tsx` | TSX | | -| `turtle` | Turtle | | -| `twig` | Twig | | -| `typescript` | TypeScript | `ts` | -| `v` | V | | -| `vb` | Visual Basic | `cmd` | -| `verilog` | Verilog | | -| `vhdl` | VHDL | | -| `viml` | Vim Script | `vim`, `vimscript` | -| `vue-html` | Vue HTML | | -| `vue` | Vue | | -| `vyper` | Vyper | `vy` | -| `wasm` | WebAssembly | | -| `wenyan` | Wenyan | `文言` | -| `wgsl` | WGSL | | -| `wolfram` | Wolfram | `wl` | -| `xml` | XML | | -| `xsl` | XSL | | -| `yaml` | YAML | `yml` | -| `zenscript` | ZenScript | | -| `zig` | zig | | - - -## Load Custom Languages - -You can load custom languages by passing a TextMate grammar object into the langs array. - -```ts -import { getHighlighter } from 'shikiji' - -const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8')) - -const highlighter = await getHighlighter({ - langs: [myLang] -}) - -const html = highlighter.codeToHtml(code, { - lang: 'my-lang', -}) -``` - -You can also load languages after the highlighter has been created. - -```ts -import { getHighlighter } from 'shikiji' - -const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8')) - -const highlighter = await getHighlighter() - -await highlighter.loadLanguage(myLang) // <-- - -const html = highlighter.codeToHtml(code, { - lang: 'my-lang', -}) -``` - -### Migrate from Shiki - -Since `shikiji` is environment agnostic, that means we don't have access to the file system. That means the `path` property `shiki` supports is not available in `shikiji`. Instead, you need to read them in yourself and pass the object. For example: - -```ts -const highlighter = await getHighlighter({ - langs: [ - { - name: 'vue-vine', - scopeName: 'source.vue-vine', - // ‼️ This would not work! - path: join(__dirname, './vine-ts.tmLanguage.json'), - embeddedLangs: [ - 'vue-html', - 'css', - 'scss', - 'sass', - 'less', - 'stylus', - ], - }, - ] -}) -``` - -Instead, load that file yourself (via `fs`, `import()`, `fetch()`, etc.) and pass the object: - -```ts -const vineGrammar = JSON.parse(fs.readFileSync(join(__dirname, './vine-ts.tmLanguage.json'), 'utf8')) + -const highlighter = await getHighlighter({ - langs: [ - { - name: 'vue-vine', - scopeName: 'source.vue-vine', - embeddedLangs: [ - 'vue-html', - 'css', - 'scss', - 'sass', - 'less', - 'stylus', - ], - ...vineGrammar - }, - ] -}) -``` +For loading your custom languages, please reference to [this guide](/guide/load-lang). diff --git a/docs/themes.md b/docs/themes.md index 9c51f430..5f709f02 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -1,76 +1,7 @@ # Themes -## All Themes - Inherited from [`shiki`](https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes), here are all the themes bundled in `shikiji`. - -| ID | -| --- | -| `dark-plus` | -| `dracula` | -| `dracula-soft` | -| `github-dark` | -| `github-dark-dimmed` | -| `github-light` | -| `light-plus` | -| `material-theme` | -| `material-theme-darker` | -| `material-theme-lighter` | -| `material-theme-ocean` | -| `material-theme-palenight` | -| `min-dark` | -| `min-light` | -| `monokai` | -| `nord` | -| `one-dark-pro` | -| `poimandres` | -| `rose-pine` | -| `rose-pine-dawn` | -| `rose-pine-moon` | -| `slack-dark` | -| `slack-ochin` | -| `solarized-dark` | -| `solarized-light` | -| `vitesse-black` | -| `vitesse-dark` | -| `vitesse-light` | - - -## Load Custom Themes - -You can load custom themes by passing a `Theme` object into the themes array. - -```ts -import { getHighlighter } from 'shikiji' - -const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8')) - -const highlighter = await getHighlighter({ - themes: [myTheme] -}) - -const html = highlighter.codeToHtml(code, { - lang: 'javascript', - theme: 'my-theme' -}) -``` - -You can also load themes after the highlighter has been created. - -```ts -import { getHighlighter } from 'shikiji' - -const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8')) - -const highlighter = await getHighlighter() - -await highlighter.loadTheme(myTheme) // <-- - -const html = highlighter.codeToHtml(code, { - lang: 'javascript', - theme: 'my-theme' -}) -``` + -The theme should be a TextMate theme in JSON object. For example, [it should looks like this](https://github.com/antfu/vscode-theme-vitesse/blob/main/themes/vitesse-dark.json). +For loading your custom themes, please reference to [this guide](/guide/load-theme). diff --git a/packages/shikiji/scripts/prepare/themes.ts b/packages/shikiji/scripts/prepare/themes.ts index 44420784..3c0abf49 100644 --- a/packages/shikiji/scripts/prepare/themes.ts +++ b/packages/shikiji/scripts/prepare/themes.ts @@ -2,9 +2,12 @@ import fs from 'fs-extra' import { BUNDLED_THEMES } from 'shiki' import { COMMENT_HEAD } from './constants' +const allThemes = BUNDLED_THEMES + .sort() + .filter(i => i !== 'css-variables') + export async function prepareTheme() { - const themes = BUNDLED_THEMES.sort() - .filter(i => i !== 'css-variables') + const themes = allThemes .map((id) => { const theme = fs.readJSONSync(`./node_modules/shiki/themes/${id}.json`) @@ -39,11 +42,8 @@ export const bundledThemes = Object.fromEntries(bundledThemesInfo.map(i => [i.id ) await fs.writeJSON( 'src/assets/themes.json', - BUNDLED_THEMES - .filter(i => i !== 'css-variables') - .map(i => ({ - id: i, - })), + allThemes + .map(i => ({ id: i })), { spaces: 2 }, ) } @@ -75,7 +75,10 @@ function guessThemeName(id: string, theme: any) { if (theme.displayName) return theme.displayName let name: string = theme.name || id - name = name.split(/[_-]/).map(i => i[0].toUpperCase() + i.slice(1)).join(' ') - name = name.replace(/github/ig, 'GitHub') + name = name.split(/[_-]/) + .map(i => i[0].toUpperCase() + i.slice(1)) + .join(' ') + .replace(/github/ig, 'GitHub') + .replace('Rose Pine', 'Rosé Pine') return name } diff --git a/packages/shikiji/src/assets/themes.ts b/packages/shikiji/src/assets/themes.ts index 600d90ee..23e9ebaa 100644 --- a/packages/shikiji/src/assets/themes.ts +++ b/packages/shikiji/src/assets/themes.ts @@ -123,19 +123,19 @@ export const bundledThemesInfo: BundledThemeInfo[] = [ }, { "id": "rose-pine", - "name": "Rose Pine", + "name": "Rosé Pine", "type": "dark", "import": (() => import('shiki/themes/rose-pine.json')) as unknown as DynamicThemeReg }, { "id": "rose-pine-dawn", - "name": "Rose Pine Dawn", + "name": "Rosé Pine Dawn", "type": "light", "import": (() => import('shiki/themes/rose-pine-dawn.json')) as unknown as DynamicThemeReg }, { "id": "rose-pine-moon", - "name": "Rose Pine Moon", + "name": "Rosé Pine Moon", "type": "dark", "import": (() => import('shiki/themes/rose-pine-moon.json')) as unknown as DynamicThemeReg }, diff --git a/scripts/readme.ts b/scripts/readme.ts deleted file mode 100644 index 665931e3..00000000 --- a/scripts/readme.ts +++ /dev/null @@ -1,40 +0,0 @@ -import fs from 'fs-extra' - -function replaceMarker(code: string, marker: string, content: string) { - const start = `` - const end = `` - const regex = new RegExp(`${start}([\\s\\S]*)${end}`) - - return code.replace(regex, `${start}\n${content.trim()}\n${end}`) -} - -async function run() { - let mdLangs = await fs.readFile('docs/languages.md', 'utf8') - const langs = await fs.readJSON('packages/shikiji/src/assets/langs.json') as { id: string, name?: string, aliases?: string[] }[] - mdLangs = replaceMarker( - mdLangs, - 'all-languages', - [ - '| ID | Name | Aliases |', - '| --- | --- | --- |', - ...langs.map(i => `| \`${i.id}\` | ${i.name || i.id} | ${i.aliases?.map(i => `\`${i}\``).join(', ') || ''} |`), - ].join('\n'), - ) - await fs.writeFile('docs/languages.md', mdLangs, 'utf-8') - - // ---- Themes - let mdThemes = await fs.readFile('docs/themes.md', 'utf8') - const themes = await fs.readJSON('packages/shikiji/src/assets/themes.json') as { id: string, name?: string }[] - mdThemes = replaceMarker( - mdThemes, - 'all-themes', - [ - '| ID |', - '| --- |', - ...themes.map(i => `| \`${i.id}\` |`), - ].join('\n'), - ) - await fs.writeFile('docs/themes.md', mdThemes, 'utf-8') -} - -run()