Languages and themes

Ferriki maintains its own catalog: a curated set of TextMate grammars, including embedding dependencies, and 65 themes. The package ships catalog metadata; grammar and theme payloads are downloaded and cached on first use by an asynchronous API call.

The standard catalog contains 67 standard grammars and 27 support grammars, 94 entries in all. Support grammars handle embedded syntax and injections; they are listed separately below.

See Ferriki vs Prism for real TypeScript, TSX, C++, Go, Rust, CSS, HTML, and Astro outputs, including the token distinctions available to themes.

Supported grammars

JSON, JSONC, JSON5, Markdown, MDX, YAML, and TOML are all included, along with Handlebars, Liquid, and Glimmer's .gjs and .gts components. The tables group the current catalog by typical use. Each row shows the ID to pass as lang, followed by any interchangeable aliases.

Standard languages

Name a language by its ID or one of its aliases (ts, rs, sh, …):

import { bundledLanguages, bundledLanguagesAlias, createHighlighter } from "@ferriki/core";

const highlighter = await createHighlighter({
  langs: ["typescript", bundledLanguages.rust],
  themes: ["github-dark"],
});

const html = highlighter.codeToHtml("const answer = 42", {
  lang: bundledLanguagesAlias.ts,
  theme: "github-dark",
});
highlighter.dispose();

Required embedded languages load with their host: HTML brings CSS and JavaScript for <style> and <script> blocks. Markdown and MDX keep optional embeddings lazy. Load the languages used in your documents explicitly; code fences follow the host grammar's supported fence rules.

JavaScript, TypeScript, JSX, and TSX also load HTML/SVG and CSS injections automatically. Lit's html, svg, and css templates, Styled Components, Emotion's tagged templates and CSS prop, and Styled JSX work with the host language alone. Object-based styles use the regular JavaScript/TypeScript rules.

import { createHighlighter } from "@ferriki/core";

const highlighter = await createHighlighter({
  langs: ["tsx"],
  themes: ["github-dark"],
});
let html;
try {
  html = highlighter.codeToHtml(
    'const Button = styled.button`color: red;`;\nconst icon = svg`<circle cx="10" />`;',
    { lang: "tsx", theme: "github-dark" },
  );
} finally {
  highlighter.dispose();
}

For MDX, load tsx to highlight JSX and expressions, and yaml or toml for frontmatter. For example:

import { createHighlighter } from "@ferriki/core";

const highlighter = await createHighlighter({
  langs: ["mdx", "tsx", "yaml", "toml"],
  themes: ["github-dark"],
});
let html;
try {
  html = highlighter.codeToHtml('---\ntitle: Hello\n---\n\n# Hello\n\n<Greeting name="Ada" />', {
    lang: "mdx",
    theme: "github-dark",
  });
} finally {
  highlighter.dispose();
}

Included support grammars

These grammars supply syntax rules used by other entries: component expressions, embedded templates, documentation comments, and YAML versions. Required dependencies load with their host. Optional embedded languages highlight when the application loads them, as with Markdown fences. They contribute to the total grammar count rather than representing additional independent programming languages.

Themes

Use any key of bundledThemes, such as github-light, github-dark, nord or vitesse-dark. The special theme none returns unstyled output. For light and dark output from one call, pass a themes map:

import { createHighlighter } from "@ferriki/core";

const highlighter = await createHighlighter({
  langs: ["typescript"],
  themes: ["github-light", "github-dark"],
});
let html;
try {
  html = highlighter.codeToHtml("const answer: number = 42", {
    lang: "typescript",
    themes: { light: "github-light", dark: "github-dark" },
  });
} finally {
  highlighter.dispose();
}

createCssVariablesTheme builds a theme whose colors are CSS variables, for sites that style highlighting from their own stylesheet.

For unchanged theme files with CSS classes instead of inline styles, see Class-based output.

Your own grammars and themes

The ferriki grammar fetch CLI imports external JSON TextMate grammars from files, URLs, and commit-pinned GitHub sources, validates them with the native engine, and records a source hash:

pnpm exec ferriki grammar fetch ./example.tmLanguage.json \
  --name example --aliases example-syntax --output ./example.ferriki.json

Pass the generated registration to langs or loadLanguage. Convert YAML, PLIST, and CSON to JSON before using this importer. Load dependency grammars explicitly. Languages outside Ferriki's standard set use this same path.

A custom grammar or theme is the same JSON-shaped TextMate structure Shiki accepts. Ferriki validates it before it reaches the native engine:

import myGrammar from "./my-language.tmLanguage.json" with { type: "json" };

await highlighter.loadLanguage({ ...myGrammar, name: "my-language" });
highlighter.codeToHtml(source, { lang: "my-language", theme: "github-dark" });

A language registration needs name, scopeName and valid patterns; a theme needs name and valid settings. Aliases of your own apply to one highlighter; the standard aliases cannot be overwritten.