Skip to content

docs(readme): draft changes for clarifying options #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
julie-ng wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(readme): draft changes for clarifying options #60

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
07d0c8c
docs(readme): draft changes for clarifying options
julie-ng Jan 7, 2026
2203923
Update types in README for configuration options
gxres042 Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 30 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,35 @@ export default defineNuxtConfig({

Available options:

- `bundledThemes` and `bundledLangs` can be configured to set bundled themes and languages.
- `defaultTheme` and `defaultLang` can be configured to set default theme and language.
- `dynamic` can be configured to set whether languages are dynamically loaded. (in this way, all languages will be bundled)
- `langAlias` can be configured to set language aliases.
- `highlightOptions` can be configured to set highlight defaults.
| Property | Type | Description |
|:--|:--|:--|
| `bundledLangs` | `BundledLanguage[]` | Refer to the Shiki docs for a [list of supported languages](https://shiki.style/languages). |
| `bundledThemes` | `BundledTheme[]` | List of themes to bundle, e.g. `['min-light', 'min-dark']` |
| `defaultLang` | `BundledLanguage` | Sets the default language. |
| `defaultTheme` | <code>BundledTheme \| Record&lt;'dark' \| 'light' \| (string &amp; {}), BundledTheme&gt;</code> | Configure a single default theme, e.g. `github-light` or different themes for light and dark modes. See example below. |
|`dynamic` | Boolean | Set to `true` to dynamically load Languages, which bundles all languages. Refer to Shiki docs on [Bundles](https://shiki.style/guide/bundles) to understand how lazy dynamic imports work.|
| `langAlias` | `Record<string, string>` | Set language aliases, e.g. `{ 'my-lang': 'javascript' }` |
| `highlightOptions` | `HighlightOptions` | Set highlight defaults. |

### Custom Themes for light and dark mode

By [default](./src/module.ts) nuxt-shiki comes bundled with the `min-light` and `min-dark` [themes](https://shiki.style/themes). To use different themes, update the `bundledThemes` and `defaultTheme` properties, for example:

```js
export default defineNuxtConfig({
modules: ['nuxt-shiki'],
shiki: {
bundledThemes: ['github-light', 'material-theme-palenight'],
defaultTheme: {
light: 'github-light',
dark: 'material-theme-palenight'
}
}
})
```

> [!NOTE]
> Themes can only be configured via the `defaultTheme` option. It is not possible to override themes in the `<Shiki>` component.
Copy link
Collaborator

@gxres042 gxres042 Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I make a mistake...... You can override highlight theme by setting highlightOptions.themes on <Shiki /> component.

Copy link
Author

@julie-ng julie-ng Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really? Maybe I am doing it wrong… but I have tried theme and :highlightOptions (as well as :highlight-options), and none of those work for me.

Although I am in my browser's default light mode, with the code above I would expect to see a dark themed code block. But, I still get the light theme.

<Shiki v-if="data" lang="json" :code="JSON.stringify(data, null, 2)" theme="material-theme-palenight" />
<Shiki v-if="data" lang="json" :code="JSON.stringify(data, null, 2)" :highlightOptions="{ theme: 'material-theme-palenight' }" />

What would be the correct syntax if we want to have a custom theme on a per component basis?

Copy link
Collaborator

@gxres042 gxres042 Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

<script setup lang="ts">
const code = ref<string>(/* js */ `
// Try editing in the left panel!
console.log('Hello, World!')
`)
const highlightOptions = ref({
  themes: {
    light: 'one-light',
    dark: 'one-dark-pro',
  },
})
</script>

<template>
  <Shiki id="shiki" lang="js" :highlight-options="highlightOptions" :code="code" />
</template>

or

<script setup lang="ts">
const code = ref<string>(/* js */ `
// Try editing in the left panel!
console.log('Hello, World!')
`)
const highlightOptions = ref({
  theme: 'one-dark-pro',
})
</script>

<template>
  <Shiki id="shiki" lang="js" :highlight-options="highlightOptions" :code="code" />
</template>


## `<Shiki>` component

Expand Down Expand Up @@ -154,4 +178,4 @@ npm run test:watch

# Release new version
npm run release
```
```