carta-md
Version:
A lightweight, fully customizable, Markdown editor
281 lines (280 loc) • 8.89 kB
TypeScript
import * as shiki from 'shiki';
import type { Intellisense } from './utils';
/**
* Custom TextMate grammar rule for the highlighter.
*/
export type GrammarRule = {
name: string;
type: 'block' | 'inline';
definition: shiki.LanguageRegistration['repository'][string];
};
/**
* Custom TextMate highlighting rule for the highlighter.
*/
export type HighlightingRule = {
light: NonNullable<shiki.ThemeRegistration['tokenColors']>[number];
dark: NonNullable<shiki.ThemeRegistration['tokenColors']>[number];
};
/**
* Language for the highlighter.
*/
export type Language = Intellisense<shiki.BundledLanguage | CustomMarkdownLangName>;
/**
* Theme name for the highlighter.
*/
export type ThemeName = Intellisense<shiki.BundledTheme | DefaultLightThemeName | DefaultDarkThemeName>;
/**
* Theme for the highlighter.
*/
export type Theme = ThemeName | shiki.ThemeRegistration;
/**
* Dual theme for light and dark mode.
*/
export type DualTheme = {
light: Theme;
dark: Theme;
};
/**
* Shiki options for the highlighter.
*/
export type ShikiOptions = {
themes?: Array<shiki.ThemeInput | shiki.StringLiteralUnion<shiki.BundledTheme>>;
langs?: (shiki.LanguageInput | shiki.StringLiteralUnion<shiki.BundledLanguage> | shiki.SpecialLanguage)[];
};
/**
* Options for the highlighter.
*/
export type HighlighterOptions = {
/**
* Custom grammar rules for the highlighter.
*/
grammarRules: GrammarRule[];
/**
* Custom highlighting rules for the highlighter.
*/
highlightingRules: HighlightingRule[];
/**
* Theme for the highlighter.
*/
theme: Theme | DualTheme;
/**
* Additional options for shiki.
*/
shiki?: ShikiOptions;
};
type CustomMarkdownLangName = Awaited<(typeof import('./assets/markdown'))['default']['name']>;
type DefaultLightThemeName = Awaited<(typeof import('./assets/theme-light'))['default']['name']>;
type DefaultDarkThemeName = Awaited<(typeof import('./assets/theme-dark'))['default']['name']>;
export declare const customMarkdownLangName: CustomMarkdownLangName;
export declare const defaultLightThemeName: DefaultLightThemeName;
export declare const defaultDarkThemeName: DefaultDarkThemeName;
/**
* Load the return the default light and dark themes.
* @returns The default light and dark themes.
*/
export declare function loadDefaultTheme(): Promise<{
light: {
displayName: "Carta Light";
name: "carta-light";
semanticHighlighting: true;
fg: string;
bg: string;
tokenColors: ({
scope: string[];
settings: {
foreground: string;
fontStyle?: undefined;
background?: undefined;
};
} | {
scope: string;
settings: {
foreground: string;
fontStyle?: undefined;
background?: undefined;
};
} | {
scope: string;
settings: {
fontStyle: string;
foreground: string;
background?: undefined;
};
} | {
scope: string;
settings: {
background: string;
fontStyle: string;
foreground: string;
};
} | {
scope: string[];
settings: {
fontStyle: string;
foreground: string;
background?: undefined;
};
} | {
scope: string[];
settings: {
background: string;
foreground: string;
fontStyle?: undefined;
};
})[];
type: "light";
};
dark: {
displayName: "Carta Dark";
name: "carta-dark";
semanticHighlighting: true;
fg: string;
bg: string;
tokenColors: ({
scope: string[];
settings: {
foreground: string;
fontStyle?: undefined;
background?: undefined;
};
} | {
scope: string;
settings: {
foreground: string;
fontStyle?: undefined;
background?: undefined;
};
} | {
scope: string;
settings: {
fontStyle: string;
foreground: string;
background?: undefined;
};
} | {
scope: string;
settings: {
background: string;
fontStyle: string;
foreground: string;
};
} | {
scope: string[];
settings: {
fontStyle: string;
foreground: string;
background?: undefined;
};
} | {
scope: string[];
settings: {
background: string;
foreground: string;
fontStyle?: undefined;
};
})[];
type: "light";
};
}>;
/**
* Checks if a language is a bundled language.
* @param lang The language to check.
* @returns Whether the language is a bundled language.
*/
export declare const isBundleLanguage: (lang: string) => lang is shiki.BundledLanguage;
/**
* Checks if a theme is a bundled theme.
* @param theme The theme to check.
* @returns Whether the theme is a bundled theme.
*/
export declare const isBundleTheme: (theme: string) => theme is shiki.BundledTheme;
/**
* Checks if a theme is a dual theme.
* @param theme The theme to check.
* @returns Whether the theme is a dual theme.
*/
export declare const isDualTheme: (theme: Theme | DualTheme) => theme is DualTheme;
/**
* Checks if a theme is a single theme.
* @param theme The theme to check.
* @returns Whether the theme is a single theme.
*/
export declare const isSingleTheme: (theme: Theme | DualTheme) => theme is Theme;
/**
* Checks if a theme is a theme registration.
* @param theme The theme to check.
* @returns Whether the theme is a theme registration.
*/
export declare const isThemeRegistration: (theme: Theme) => theme is shiki.ThemeRegistration;
/**
* Injects custom grammar rules into the language definition.
* @param lang The language definition to inject the rules into.
* @param rules The grammar rules to inject.
* @returns The language definition with the injected rules.
*/
export declare function injectGrammarRules(lang: Awaited<(typeof import('./assets/markdown'))['default']>, rules: GrammarRule[]): void;
/**
* Injects custom highlighting rules into the theme.
* @param theme The theme to inject the rules into.
* @param rules The highlighting rules to inject.
* @returns The theme with the injected rules.
*/
export declare function injectHighlightRules(theme: shiki.ThemeRegistration, rules: HighlightingRule[]): void;
/**
* Highlighter instance for the highlighter manager.
*/
export type Highlighter = {
/**
* Shortcut for highlighting a code block using the highlighter specific language
* and theme.
* @param code The code to highlight.
* @returns The highlighted code.
*/
codeToHtml: (code: string) => string;
/**
* Gets the underlying shiki highlighter instance.
* @returns The underlying shiki highlighter instance.
*/
shikiHighlighter: () => ShikiHighlighter;
settings: {
/**
* The language hash assigned to this highlighter instance.
* It's the id of the language registered to shiki.
*/
langHash: string;
/**
* The theme hash assigned to this highlighter instance.
* It's the id of the theme registered to shiki.
*/
themeHash: string | {
light: string;
dark: string;
};
};
/**
* Reexported utilities functions.
*/
utils: {
isBundleLanguage: typeof isBundleLanguage;
isBundleTheme: typeof isBundleTheme;
isDualTheme: typeof isDualTheme;
isSingleTheme: typeof isSingleTheme;
isThemeRegistration: typeof isThemeRegistration;
};
};
export type ShikiHighlighter = shiki.HighlighterGeneric<shiki.BundledLanguage, shiki.BundledTheme>;
export type HighlighterManager = {
shikiHighlighter: ShikiHighlighter;
highlighters: Highlighter[];
};
export declare function loadHighlighter(options: HighlighterOptions): Promise<Highlighter>;
/**
* Load all nested languages found in the markdown text into the highlighter.
* @param highlighter The highlighter instance.
* @param text The text to parse for nested languages.
* @returns Whether the highlighter was updated with new languages.
*/
export declare const loadNestedLanguages: (highlighter: Highlighter, text: string) => Promise<{
updated: boolean;
}>;
export {};