TIL: Using Twoslash with Shiki and Astro

| View comments on Hacker News

Do you want code snippets like below on your Astro site?

Note: you can hover over types to see their definitions.

function function createLabel<T extends number | string>(idOrName: T): NameOrId<T>createLabel<function (type parameter) T in createLabel<T extends number | string>(idOrName: T): NameOrId<T>T extends number | string>(idOrName: T extends number | stringidOrName: function (type parameter) T in createLabel<T extends number | string>(idOrName: T): NameOrId<T>T): type NameOrId<T extends number | string> = T extends number ? IdLabel : NameLabelNameOrId<function (type parameter) T in createLabel<T extends number | string>(idOrName: T): NameOrId<T>T> {
  throw "unimplemented";
}

let let a: NameLabela = function createLabel<"typescript">(idOrName: "typescript"): NameLabelcreateLabel("typescript");

It’s super easy. In your astro.config.ts file, add the following:

import { function rendererRich(options?: RendererRichOptions): TwoslashRenderer
An alternative renderer that providers better prefixed class names, with syntax highlight for the info text.
rendererRich
, function transformerTwoslash(options?: TransformerTwoslashIndexOptions): ShikiTransformer
Factory function to create a Shiki transformer for twoslash integrations.
transformerTwoslash
} from "@shikijs/twoslash";
export default defineConfig<never, never, never>(config: AstroUserConfig<never, never, never>): AstroUserConfig<never, never, never>
See the full Astro Configuration API Documentation https://astro.build/config
defineConfig
({
AstroUserConfig<never, never, never>.markdown?: {
    shikiConfig?: Partial<ShikiConfig>;
    syntaxHighlight?: {
        type?: SyntaxHighlightConfigType;
        excludeLangs?: string[];
    } | SyntaxHighlightConfigType | false;
    ... 4 more ...;
    remarkRehype?: RemarkRehype;
} | undefined
@docs@kindheading@nameMarkdown Options
markdown
: {
shikiConfig?: Partial<ShikiConfig> | undefined
@docs@namemarkdown.shikiConfig@typeraw{Partial<ShikiConfig>}@descriptionShiki is our default syntax highlighter. You can configure all options via the `markdown.shikiConfig` object: ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; export default defineConfig({ markdown: { shikiConfig: { // Choose from Shiki's built-in themes (or add your own) // https://shiki.style/themes theme: 'dracula', // Alternatively, provide multiple themes // See note below for using dual light/dark themes themes: { light: 'github-light', dark: 'github-dark', }, // Disable the default colors // https://shiki.style/guide/dual-themes#without-default-color // (Added in v4.12.0) defaultColor: false, // Add custom languages // Note: Shiki has countless langs built-in, including .astro! // https://shiki.style/languages langs: [], // Add custom aliases for languages // Map an alias to a Shiki language ID: https://shiki.style/languages#bundled-languages // https://shiki.style/guide/load-lang#custom-language-aliases langAlias: { cjs: "javascript" }, // Enable word wrap to prevent horizontal scrolling wrap: true, // Add custom transformers: https://shiki.style/guide/transformers // Find common transformers: https://shiki.style/packages/transformers transformers: [], }, }, }); ``` See the [code syntax highlighting guide](/en/guides/syntax-highlighting/) for usage and examples.
shikiConfig
: {
transformers?: ShikiTransformer[] | undefined
Shiki transformers to customize the generated HTML by manipulating the hast tree.
transformers
: [
function transformerTwoslash(options?: TransformerTwoslashIndexOptions): ShikiTransformer
Factory function to create a Shiki transformer for twoslash integrations.
transformerTwoslash
({
TransformerTwoslashOptions.renderer?: TwoslashRenderer | undefined
Custom renderers to decide how each info should be rendered
renderer
: function rendererRich(options?: RendererRichOptions): TwoslashRenderer
An alternative renderer that providers better prefixed class names, with syntax highlight for the info text.
rendererRich
(),
}), ], }, }, });

Import this CSS in your layout:

import "@shikijs/twoslash/style-rich.css";

Add the following CSS and import it in your layout:

// fixes an issue where type popups are cut off
.astro-code {
  overflow: visible !important;
}

Bonus: enable an automatic light & dark mode. Add the following CSS from Shiki’s documentation:

@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
    color: var(--shiki-dark) !important;
    background-color: var(--shiki-dark-bg) !important;
    /* Optional, if you also want font styles */
    font-style: var(--shiki-dark-font-style) !important;
    font-weight: var(--shiki-dark-font-weight) !important;
    text-decoration: var(--shiki-dark-text-decoration) !important;
  }
}

Add the following to your astro.config.ts:

export default defineConfig<never, never, never>(config: AstroUserConfig<never, never, never>): AstroUserConfig<never, never, never>
See the full Astro Configuration API Documentation https://astro.build/config
defineConfig
({
AstroUserConfig<never, never, never>.markdown?: {
    shikiConfig?: Partial<ShikiConfig>;
    syntaxHighlight?: {
        type?: SyntaxHighlightConfigType;
        excludeLangs?: string[];
    } | SyntaxHighlightConfigType | false;
    ... 4 more ...;
    remarkRehype?: RemarkRehype;
} | undefined
@docs@kindheading@nameMarkdown Options
markdown
: {
shikiConfig?: Partial<ShikiConfig> | undefined
@docs@namemarkdown.shikiConfig@typeraw{Partial<ShikiConfig>}@descriptionShiki is our default syntax highlighter. You can configure all options via the `markdown.shikiConfig` object: ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; export default defineConfig({ markdown: { shikiConfig: { // Choose from Shiki's built-in themes (or add your own) // https://shiki.style/themes theme: 'dracula', // Alternatively, provide multiple themes // See note below for using dual light/dark themes themes: { light: 'github-light', dark: 'github-dark', }, // Disable the default colors // https://shiki.style/guide/dual-themes#without-default-color // (Added in v4.12.0) defaultColor: false, // Add custom languages // Note: Shiki has countless langs built-in, including .astro! // https://shiki.style/languages langs: [], // Add custom aliases for languages // Map an alias to a Shiki language ID: https://shiki.style/languages#bundled-languages // https://shiki.style/guide/load-lang#custom-language-aliases langAlias: { cjs: "javascript" }, // Enable word wrap to prevent horizontal scrolling wrap: true, // Add custom transformers: https://shiki.style/guide/transformers // Find common transformers: https://shiki.style/packages/transformers transformers: [], }, }, }); ``` See the [code syntax highlighting guide](/en/guides/syntax-highlighting/) for usage and examples.
shikiConfig
: {
theme?: ThemePresets | ThemeRegistration | ThemeRegistrationRaw | undefinedtheme: "github-dark", themes?: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw> | undefinedthemes: { light: "github-light"light: "github-light", dark: "github-dark"dark: "github-dark", }, }, }, });

You can try it on this site by toggling your browser’s or operating system’s dark mode.

Check out Shiki’s Twoslash documentation for details.

Recent posts from blogs that I like

From the Commedia dell’Arte to Punch and Judy 1

Pierrot, Harlequin and other characters from the early professional theatre seen in paintings by Watteau, Goya and others.

via The Eclectic Light Company

Bloom filters

The original motivation for the creation of Bloom filters is efficient set membership, using a probabilistic approach to significantly reduce the time and space required to reject items that are not members in a certain set. The data structure was proposed by Burton Bloom in a 1970 paper titled "Spa...

via Eli Bendersky

Two publishers and three authors fail to understand what "vibe coding" means

via Simon Willison