@primeui-devkit/markdown-core 0.1.0-beta.1 → 0.1.0-rc.1

package/README.md

@@ -48,14 +48,28 @@ const tree = await highlightTree(await parse(source));
 Both themes are emitted at once, so a page switches between light and dark without
 highlighting anything again.
 
-Only registered themes work. Passing a name the backend does not know produces
-unhighlighted output without reporting anything, so `highlightTree` checks first and
-throws with the list of what is available — `availableThemes()` returns the same list.
+Passing a theme name the backend does not know produces unhighlighted output without
+reporting anything, so `highlightTree` checks names first and throws with the list of what
+is available — `availableThemes()` returns the same list.
 
 ```ts
 await highlightTree(tree, { themes: { light: 'material-theme-lighter', dark: 'material-theme-palenight' } });
 ```
 
+A theme the backend does not ship is passed as a definition instead of a name. `languages`
+preloads grammars, which keeps a build to the ones it uses rather than loading every one on
+demand, and `transformers` is where line markers such as `[!code highlight]` come from.
+
+```ts
+import { transformerNotationHighlight } from '@shikijs/transformers';
+
+await highlightTree(tree, {
+    themes: { light: (await import('shiki/themes/github-light.mjs')).default, dark: 'material-theme-palenight' },
+    languages: [(await import('shiki/langs/vue.mjs')).default],
+    transformers: [transformerNotationHighlight()]
+});
+```
+
 `@primeui-devkit/highlighter` is a separate package for highlighting a standalone snippet
 to HTML. Neither depends on the other: this one works on a parsed tree, that one on a
 string, and a repository takes whichever it needs.

package/dist/plugins/highlight.d.ts

@@ -18,18 +18,43 @@ import { ComarkPlugin, ComarkTree } from 'comark';
  * would tie every caller to that engine through a package whose whole purpose is to keep
  * it out of sight.
  */
+/**
+ * A theme, either by name or as a full definition.
+ *
+ * The definition form is deliberately opaque: describing it would pull the highlighting
+ * engine's types into this package's public surface, which is what it exists to avoid.
+ * Pass the value a `shiki/themes/*` module default-exports.
+ */
+type HighlightTheme = string | (object & {
+    name?: string;
+});
+/** A language definition, as a `shiki/langs/*` module default-exports. */
+type HighlightLanguage = object;
+/** A code-block transformer, as `@shikijs/transformers` returns. */
+type HighlightTransformer = object;
 interface HighlightOptions {
     /**
      * Themes to render with. Both are emitted, so a page can switch between light and dark
      * without highlighting anything again.
      *
-     * Only registered themes work. A name the backend does not know leaves every block
-     * unhighlighted without reporting anything, so {@link highlightTree} checks first.
+     * A registered name works, as does a theme definition — pass the latter to use a theme
+     * the backend does not ship. Names are checked first, because a name the backend does
+     * not know leaves every block unhighlighted without reporting anything.
      */
     themes?: {
-        light: string;
-        dark: string;
+        light: HighlightTheme;
+        dark: HighlightTheme;
     };
+    /**
+     * Languages to preload. Left unset, languages load on demand, which needs the backend's
+     * full bundle; preloading keeps a build to the grammars it actually uses.
+     */
+    languages?: HighlightLanguage[];
+    /**
+     * Transformers applied to every block — line markers such as `[!code highlight]` come
+     * from these.
+     */
+    transformers?: HighlightTransformer[];
     /** Whether to inline the theme's background and colour on the block. Defaults to `false`. */
     inlineStyles?: boolean;
 }
@@ -64,4 +89,4 @@ declare function highlightTree(tree: ComarkTree, options?: HighlightOptions): Pr
  */
 declare function highlight(options?: HighlightOptions): ComarkPlugin<any, any>;
 
-export { type HighlightOptions, availableThemes, highlight as default, defaultThemes, highlightTree };
+export { type HighlightLanguage, type HighlightOptions, type HighlightTheme, type HighlightTransformer, availableThemes, highlight as default, defaultThemes, highlightTree };

package/dist/plugins/highlight.js

@@ -1 +1 @@
-import s,{getHighlighter,highlightCodeBlocks}from'comark/plugins/highlight';var c={light:"material-theme-lighter",dark:"material-theme-palenight"};async function g(){return (await getHighlighter()).getLoadedThemes?.()??[]}async function p(t,i={}){let{themes:e,inlineStyles:a=false}=i;if(e){let r=await g(),n=[e.light,e.dark].filter(l=>!r.includes(l));if(n.length>0)throw new Error(`Unknown theme${n.length>1?"s":""}: ${n.join(", ")}. Available: ${r.join(", ")}.`)}return await highlightCodeBlocks(t,{...e?{themes:e}:{},preStyles:a})}function m(t={}){let{themes:i,inlineStyles:e=false}=t;return s({...i?{themes:i}:{},preStyles:e})}export{g as availableThemes,m as default,c as defaultThemes,p as highlightTree};
+import l,{getHighlighter,highlightCodeBlocks}from'comark/plugins/highlight';var c=e=>e?[e.light,e.dark].filter(t=>typeof t=="string"):[],y={light:"material-theme-lighter",dark:"material-theme-palenight"};async function d(){return (await getHighlighter()).getLoadedThemes?.()??[]}async function T(e,t={}){let{themes:i,languages:n,transformers:r,inlineStyles:s=false}=t,g=c(i);if(g.length>0){let h=await d(),a=g.filter(o=>!h.includes(o));if(a.length>0)throw new Error(`Unknown theme${a.length>1?"s":""}: ${a.join(", ")}. Available: ${h.join(", ")}.`)}return await highlightCodeBlocks(e,{...i?{themes:i}:{},...n?{languages:n}:{},...r?{transformers:r}:{},preStyles:s})}function f(e={}){let{themes:t,languages:i,transformers:n,inlineStyles:r=false}=e;return l({...t?{themes:t}:{},...i?{languages:i}:{},...n?{transformers:n}:{},preStyles:r})}export{d as availableThemes,f as default,y as defaultThemes,T as highlightTree};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primeui-devkit/markdown-core",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-rc.1",
   "description": "Framework-agnostic markdown engine. Parses markdown with component directives into a serializable tree consumed by the framework renderers. The parsing backend is an internal implementation detail.",
   "author": "PrimeTek Informatics",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -110,13 +110,14 @@
     }
   },
   "devDependencies": {
+    "@shikijs/transformers": "^4.4.2",
     "cross-env": "^10.1.0",
     "tsup": "^8.5.1",
     "typescript": "~6.0.0",
     "vitest": "4.1.10",
+    "@primeui-devkit/ts-config": "0.0.0",
     "@primeui-devkit/test-config": "0.0.0",
-    "@primeui-devkit/bundler": "0.0.0",
-    "@primeui-devkit/ts-config": "0.0.0"
+    "@primeui-devkit/bundler": "0.0.0"
   },
   "publishConfig": {
     "access": "public"