@paperclover/markodown 1.0.0-rc.10

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright 2026 clover caruso
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# Markodown
+
+> STATUS: Markodown is not yet in use at paperclover.net. However, the API is
+> complete and the library is functional. Give it a try!
+
+This is a weird markup language that combines features of [Markdown] and
+[Marko]. You can think of this as an alternative universe to MDX. Since Marko
+components are really easy to write, it makes this a great tool for writing
+interactive blog posts. Markdown is compiled directly into `.marko` syntax,
+leveraging the existing ecosystem.
+
+[Markdown]: https://en.wikipedia.org/wiki/Markdown
+[Marko]: https://markojs.com/
+
+> - [Usage](#usage)
+>   - [Components](#components)
+>   - [Outline / Table of Contents](#outline-table-of-contents)
+>   - [Frontmatter](#frontmatter)
+>   - [Comments](#comments)
+>   - [Paragraph Detection](#paragraph-detection)
+>   - [Static Statements](#static-statements)
+> - [Config](#config)
+>   - [Frontmatter Layout Configuration](#frontmatter-layout-configuration)
+
+Here's a glance at how things look. Complete example documents in <./examples>
+
+````
+---
+// in `clover` static site generator, `export const meta` powers meta and
+// open graph tags. frontmatter becomes exports and in-scope constants.
+meta:
+  title: some interesting blog post
+  description: i could be really interesting
+  embed:
+    image: /something/fire.png
+---
+// this component will look for `blog-layout.marko`
+<blog-layout title=meta.title description=meta.description>
+
+# ${meta.title}
+
+i'm a catgirl and i love to **meow**! <rainbow-text>meow meow meow!</>
+
+```ts
+function doMyFavoriteThing() {
+  return "meow! ".repeat(Math.floor(Math.random() * 1000)).trim();
+}
+```
+
+## photos of my favorite people
+
+i love using Marko components because they're extremely concise to write.
+a lot less brace hell for non-string attributes, and more treats!
+
+<photo-grid
+  base="/friends"
+  cols=[40, 30, 30]
+  rows=[300, 400, 200]
+>
+  <@img src="IMG_4831.jpeg" />
+  <@img src="IMG_4838.jpeg" w=2 />
+  <@img src="IMG_4839.jpeg" w=2 align="top" />
+  <@img src="IMG_4833.jpeg" h=2 />
+  <@img src="IMG_4832.jpeg" w=2 />
+</>
+
+## in conclusion
+
+i love being alive. ${'<3'} from ${new Date().getFullYear()}.
+
+</blog-layout>
+````
+
+## Usage
+
+Markodown is distributed on
+[NPM](https://npmjs.com/package/@paperclover/markodown) and
+[JSR](https://jsr.io/@clo/markodown). The compiler runs anywhere JS+WASM runs.
+
+```sh
+# alias install
+npm i @clo/markodown@npm:@paperclover/markodown
+# or
+npx jsr add @clo/markodown
+```
+
+The compiler can be directly used from `transform`, and there are also plugins
+for Rollup/Rolldown/Vite and esbuild. For example, configure Markodown with
+Marko Run:
+
+```ts
+import marko from "@marko/run/vite";
+import markodown from "@clo/markodown";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    marko(),
+    markodown({
+      // optionally wrap all markdown files in a layout, this component is
+      // given a list of headers to construct a table of contents.
+      layoutImport: "../tags/markdown-layout.marko",
+      // ...more customization options are well-documented in the types.
+    }),
+  ],
+});
+```
+
+### Components
+
+All Marko features are supported, such as [tag resolution], [attribute tags],
+[class shorthands], and template expressions. This makes it so much easier to
+add complex content to your pages.
+
+```
+## cool video
+
+<clover-video src="/2025/in the summer/in the summer.mp4">
+  <@header>**music video**: in the summer</>
+</clover-video>
+
+<footer.copyright-info>
+  made with love... (c) ${new Date().getFullYear()}
+</footer>
+```
+
+[tag resolution]: https://markojs.com/docs/reference/custom-tag#relative-custom-tags
+[attribute tags]: https://markojs.com/docs/reference/language#attribute-tags
+[class shorthands]: https://markojs.com/docs/reference/language#shorthand-class-and-id
+
+### Outline / Table of Contents
+
+You can use Markodown to write blogs and long documents, then extract a table of
+contents. This is done with two mechanisms.
+
+- `layoutImport` which wraps the entire document in a component, which is given
+  three attributes. (see typescript types on the plugin / `transform` function)
+  - `content`: the rendered content.
+  - `module`: the module namespace for the compiled Markodown file.
+  - `outline`: an array of `Heading` objects.
+- `componentImports`, which can let you customize the rendering of the headers
+  themselves.
+
+Using the basic heading tags is awesome, because you can very easily customize
+the generated permalinks for each heading, and still use Markdown within the
+heading titles.
+
+```
+# my blog post
+
+<h2#markdown>about `markdown`</>
+
+...
+
+<h2#marko>about `marko`</>
+
+...
+
+<h3#marko-extras>some extra details</>
+
+...
+```
+
+### Frontmatter
+
+All frontmatter fields are converted into exports. For example, a framework that
+reads the `meta` export for Open Graph can be easily satisfied with frontmatter.
+
+```
+---
+meta:
+  title: I Love Modular Software
+  description: a very cute little post by me
+  author: clover caruso
+  embed:
+    thumbnail: /file/blog.png
+---
+
+// And since `export const` puts the value in scope, this works too:
+
+# ${meta.title}
+```
+
+### Comments
+
+Line, Block, and HTML comments work like they do in Marko/JavaScript.
+
+```
+# My Blog
+
+Text that is complete.
+
+// ## An unfinished section of the blog
+// 
+// TODO: we gotta finish it!
+```
+
+### Paragraph Detection
+
+Like Markdown, you can place content between components, but you can also place
+inline markdown anywhere between tags. Effectively, this means that text gets
+wrapped in `<p>` tags if there is a blank line above and below it.
+
+```
+<div>not wrapped</div>
+<div>
+not wrapped either
+</div>
+
+<div>
+
+this paragraph gets wrapped in a `<p>` tag!
+
+</div>
+```
+
+### Static Statements
+
+You can define module-level functions and variables,
+[same as you can in Marko](https://markojs.com/docs/reference/language#statements).
+
+```
+static function sort(items: string[]) {
+    while (!isSorted()) {
+        shuffle(items);
+    }
+    return items;
+}
+```
+
+Note that this means writing a paragraph starting with the lowercase words
+`static`, `export`, `import`, `server`, and `client` all must be escaped.
+
+```
+# All About RSC
+
+\server components are a bad idea. (markdown backslash)
+
+${"server"} components are a bad idea. (template literal)
+
+Though you can say import as long as it's not the first item.
+```
+
+## Config
+
+You can configure Markodown globally via arguments to the `transform` function.
+
+### Frontmatter Layout Configuration
+
+If frontmatter defines a `layout` property, is acts as a component import that
+wraps the page. (This can also be configured globally with the `layoutImport`
+property to `transform`).
+
+```
+---
+title: my amazing post
+layout: ../layout.marko
+---
+
+## my document
+
+yap yap
+```
+
+In `layout.marko`, you can customize extensively how the document is formatted.
+
+```marko
+import { Heading } from "@clo/markodown";
+
+export interface Input {
+  content: Marko.Body;
+  
+  /** Markdown scans for headings (h1..h6) */
+  outline: Heading[];
+  /** This is the namespace import of the main document.
+   *  You can reflect frontmatter, or do whatever with this. */
+  module: Record<string, unknown>;
+}
+
+<main>
+<h1>${input.module.title ?? "Blog Post"}</h1>
+<aside>
+  <for|heading| of=input.outline>
+    // heading content includes formatting, even custom tags.
+    <li><a href=`#${heading.id}`><${heading.content}/></a></li>
+  </for>
+</aside>
+
+<${input.content} />
+</main>
+
+// Additionally, built-in components can be altered.
+import CustomHeader from "./custom-header.marko";
+export const components = {
+  heading: CustomHeader,
+  // link, image, codeBlock, blockquote
+};
+```

package/_dist/esbuild.d.ts

@@ -0,0 +1,14 @@
+import * as markodown from "./mod.js";
+import * as marko from "@marko/compiler";
+import type * as esbuild from "esbuild";
+export type EsbuildPluginOptions = Omit<markodown.TransformOptions, "source" | "format"> & {
+  marko?: typeof marko;
+  markoOptions?: marko.Config;
+};
+/**
+ * esbuild or Bun bundling plugin. Because Bun markets itself as compatible with
+ * plugins made for esbuild, this plugin is designed to work around differences
+ * in Bun's implementation to allow it to work. Bugs reported for subtle behavior
+ * mistakes that are not present when using `esbuild` will not be fixed.
+ */ export default function esbuildPlugin(options?: EsbuildPluginOptions): esbuild.Plugin;
+//# sourceMappingURL=esbuild.d.ts.map

package/_dist/esbuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild.d.ts","sources":["../esbuild.ts"],"names":[],"mappings":"AAAA,YAAY,0BAA0B;AACtC,YAAY,6BAAoC;AAChD,iBAAiB,uBAA+B;AAIhD,YAAY,uBACR,KAAK,UAAU,kBAAkB,WAAW;EAE5C,eAAe;EACf,eAAe,MAAM;;AAGzB;;;;;CAKC,GACD,eAAe,SAAS,cACtB,UAAS,oBAAyB,GACjC,QAAQ"}

package/_dist/mod.d.ts

@@ -0,0 +1,139 @@
+/** The result of a Markodown transform */ export type Transformed = Success | Failure;
+/** Convert Markodown (`.mdo`) source code into Marko source code (`.marko`) */ export declare function transform(options: TransformOptions): Transformed;
+/**
+ * Converts a flat document outline into a nested tree. You can consume this
+ * tree with a recursive Marko component:
+
+ * ```marko
+ * <define/Recurse|input: HeadingTree|>
+ *   <a href=`#${input.id}`><${input.content} /></a>
+
+ *   <if=input.children.length>
+ *     <ul><for|item| of=input.children>
+ *       <li><Recurse ...item /></li>
+ *     </></ul>
+ *   </>
+ * </>
+ *
+ * <div#toc>
+ *   <h2>Contents:</h2>
+ *   <for|item| of=groups>
+ *     <li><Recurse ...item /></li>
+ *   </>
+ * </div>
+ * ```
+ */ export declare function outlineToTree(outline: Heading[]): HeadingTree[];
+/** Options for {@linkcode transform}. */ export interface TransformOptions {
+  /** The Markodown source code to be transformed */ source: string;
+  /**
+   * Specify the allowed output formats. For simplicity, pass `marko`. By
+   * including `html`, you can opt into a faster codepath where plain HTML is
+   * returned to you as such, when no Marko features are used.
+   * @default ["marko"]
+   */ format?: Array<"marko" | "html">;
+  /** Wraps the component in another component. Enables Table of Contents generation */ layoutImport?: string;
+  /** Import path for the module itself, passed to the layout as `module` */ selfImport?: string;
+  /** Replace built-in elements with custom components */ componentImports?: ComponentImports;
+  /**
+   * When true, disables all Marko extensions, turning this into a pure
+   * Markdown parser. Marko tags, template expressions, statements, and
+   * comments will be treated as plain text. Defaults to HTML output.
+   * @default false
+   */ markdownOnly?: boolean;
+  /**
+   * These extensions are special-cased so that Clover can re-use this on
+   * her website without maintaining a second markdown parser. I promise
+   * we are not wasting your bundle size on my features.
+   */ cloverExtensions?: CloverQuestionExtensions;
+}
+/** Replace Built In Elements */ export interface ComponentImports {
+  /** Replace (h1-h6) with this import. Receives attribute `level: number`. */ heading?: string;
+  /** Replace `pre > code` with this import. */ codeBlock?: string;
+  /** Replace links with this import. */ link?: string;
+  /** Replace images with this import. */ image?: string;
+  /** Replace blockquotes with this import. */ blockquote?: string;
+}
+/**
+ * Clover's question extensions are syntax features used on the years of backlog
+ * from https://paperclover.net/q+a. It was easier to re-implement these than
+ * convert everything into Marko. Besides, there are some extra things that
+ * make it so these must emit HTML and not Marko, so these components all
+ * emit custom HTML elements instead of imported components.
+ *
+ * Also includes `@html <raw>` block syntax for raw HTML passthrough.
+ *
+ * @internal
+ */ export interface CloverQuestionExtensions {
+  /**
+   * Element name for question blocks. Not an import path.
+   * `q: ...inline...` -> `<question>...</question>`
+   *
+   * `q: ...inline...\nq: ...inline...`
+   * ^ this inserts a `<br />` between them since theyre stuck together.
+   */ question: string;
+  /**
+   * Element name for artifact ref. Not an import path.
+   * `@its-snowing` -> `<artifactRef>its-snowing</artifactRef>`
+   */ artifactRef: string;
+  /**
+   * Element name for question ref. Not an import path.
+   * `#2602142011` -> `<questionRef>2602142011</questionRef>`
+   *
+   * Question refs are 10 or 12 numbers in a row.
+   */ questionRef: string;
+  /**
+   * Element name for Labelled redactions.
+   * `#name#` -> `<labelledRedaction>name</labelledRedaction>`
+   */ labelledRedaction: string;
+}
+/** The transformer currently supports two output formats. */ export type OutputFormat = "marko" | "html";
+/** The transform is a success when `success: true` or there are no errors. */ export interface Success {
+  /** Easy boolean to discriminate {@linkcode TransformResult} */ success: true;
+  /** The transformed text. Format is determined by `format` */ text: string;
+  /** The resolved output format of `text` */ format: OutputFormat;
+  /** List of errors, if any */ errors: [];
+}
+/** The transform is a success when `success: false` or there is at least one error. */ export interface Failure {
+  /** Easy boolean to discriminate {@linkcode TransformResult} */ success: false;
+  /** The transformed text. Format is determined by `format` */ text: null;
+  /** The resolved output format of `text` */ format: null;
+  /** List of errors, if any */ errors: [TransformError, ...TransformError[]];
+}
+/** This is passed to Markodown layouts */ export interface LayoutInput {
+  /**
+   * Scanned from heading tags, the document outline is provided flat here. You
+   * can convert it into a nested tree with {@linkcode outlineToTree}
+   */ outline: Heading[];
+  /**
+   * A copy of the Module Namespace object of the page. Use this to reflect
+   * frontmatter or other customizable exports. Don't render `module.default` as
+   * a component, since that will recursively call this layout.
+   */ module: Record<string, unknown>;
+  /** The rendered document */ // @ts-ignore fails if marko types not chilling
+  content: Marko.Body;
+}
+/**
+ * Scanned from heading tags, this represents one heading in the document. You
+ * can convert it into a nested tree with {@linkcode outlineToTree}
+ */ export interface Heading {
+  /** Which header element this corresponds to. */ level: 1 | 2 | 3 | 4 | 5 | 6;
+  /** The link ID. Derived from the `id` attribute of the heading, or generated for you otherwise. */ id: string;
+  /** The rendered heading name */ // @ts-ignore fails if marko types not chilling
+  content: Marko.Body;
+}
+/** Generated by {@linkcode outlineToTree} */ export interface HeadingTree extends Heading {
+  /** Sub-headings */ children: HeadingTree[];
+}
+export interface TransformError {
+  /** What went wrong? */ message: string;
+  /** Additional notes for the failure */ notes: TransformNote[];
+  /** One-based line */ line: number;
+  /** One-based column, byte offset */ column: number;
+}
+export interface TransformNote {
+  /** What this span is communicating */ message?: string | null;
+  /** One-based line */ line: number;
+  /** One-based column, byte offset */ column: number;
+  /** Byte length */ width: number;
+}
+//# sourceMappingURL=mod.d.ts.map

package/_dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"AAKA,wCAAwC,GACxC,YAAY,cAAc,UAAU;AAEpC,6EAA6E,GAC7E,OAAO,iBAAS,UAAU,SAAS,gBAAgB,GAAG;AAsBtD;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,iBAAS,cAAc,SAAS,SAAS,GAAG;AA2BnD,uCAAuC,GACvC,iBAAiB;EACf,gDAAgD,GAChD,QAAQ,MAAM;EACd;;;;;GAKC,GACD,SAAS,MAAM,UAAU;EACzB,mFAAmF,GACnF,eAAe,MAAM;EACrB,wEAAwE,GACxE,aAAa,MAAM;EACnB,qDAAqD,GACrD,mBAAmB;EACnB;;;;;GAKC,GACD,eAAe,OAAO;EACtB;;;;GAIC,GACD,mBAAmB;;AAGrB,8BAA8B,GAC9B,iBAAiB;EACf,0EAA0E,GAC1E,UAAU,MAAM;EAChB,2CAA2C,GAC3C,YAAY,MAAM;EAClB,oCAAoC,GACpC,OAAO,MAAM;EACb,qCAAqC,GACrC,QAAQ,MAAM;EACd,0CAA0C,GAC1C,aAAa,MAAM;;AAGrB;;;;;;;;;;CAUC,GACD,iBAAiB;EACf;;;;;;GAMC,GACD,UAAU,MAAM;EAChB;;;GAGC,GACD,aAAa,MAAM;EACnB;;;;;GAKC,GACD,aAAa,MAAM;EACnB;;;GAGC,GACD,mBAAmB,MAAM;;AAG3B,2DAA2D,GAC3D,YAAY,eAAe,UAAU;AAErC,4EAA4E,GAC5E,iBAAiB;EACf,6DAA6D,GAC7D,SAAS,IAAI;EACb,2DAA2D,GAC3D,MAAM,MAAM;EACZ,yCAAyC,GACzC,QAAQ;EACR,2BAA2B,GAC3B;;AAGF,qFAAqF,GACrF,iBAAiB;EACf,6DAA6D,GAC7D,SAAS,KAAK;EACd,2DAA2D,GAC3D,MAAM,IAAI;EACV,yCAAyC,GACzC,QAAQ,IAAI;EACZ,2BAA2B,GAC3B,SAAS,mBAAmB;;AAG9B,wCAAwC,GACxC,iBAAiB;EACf;;;GAGC,GACD,SAAS;EACT;;;;GAIC,GACD,QAAQ,OAAO,MAAM,EAAE,OAAO;EAC9B,0BAA0B,GAC1B,+CAA+C;EAC/C,SAAS,MAAM;;AAGjB;;;CAGC,GACD,iBAAiB;EACf,8CAA8C,GAC9C,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI;EAC3B,iGAAiG,GACjG,IAAI,MAAM;EACV,8BAA8B,GAC9B,+CAA+C;EAC/C,SAAS,MAAM;;AAGjB,2CAA2C,GAC3C,iBAAiB,oBAAoB;EACnC,iBAAiB,GACjB,UAAU;;AAGZ,iBAAiB;EACf,qBAAqB,GACrB,SAAS,MAAM;EACf,qCAAqC,GACrC,OAAO;EACP,mBAAmB,GACnB,MAAM,MAAM;EACZ,kCAAkC,GAClC,QAAQ,MAAM;;AAGhB,iBAAiB;EACf,oCAAoC,GACpC,UAAU,MAAM,GAAG,IAAI;EACvB,mBAAmB,GACnB,MAAM,MAAM;EACZ,kCAAkC,GAClC,QAAQ,MAAM;EACd,gBAAgB,GAChB,OAAO,MAAM"}

package/_dist/rollup.d.ts

@@ -0,0 +1,11 @@
+import * as markodown from "./mod.js";
+import * as marko from "@marko/compiler";
+import type * as rollup from "rollup";
+export type RollupPluginOptions = Omit<markodown.TransformOptions, "source" | "format"> & {
+  marko?: typeof marko;
+  markoOptions?: marko.Config;
+};
+/**
+ * Rollup bundling plugin for markodown files.
+ */ export default function rollupPlugin(options?: RollupPluginOptions): rollup.Plugin;
+//# sourceMappingURL=rollup.d.ts.map

package/_dist/rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup.d.ts","sources":["../rollup.ts"],"names":[],"mappings":"AAAA,YAAY,0BAA0B;AACtC,YAAY,6BAAoC;AAChD,iBAAiB,qBAA4B;AAG7C,YAAY,sBACR,KAAK,UAAU,kBAAkB,WAAW;EAE5C,eAAe;EACf,eAAe,MAAM;;AAGzB;;CAEC,GACD,eAAe,SAAS,aACtB,UAAS,mBAAwB,GAChC,OAAO"}

package/bindgen/markodown.d.ts

@@ -0,0 +1,42 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export enum OutputFormat {
+    Html = 0,
+    Marko = 1,
+}
+
+export function transform(src: string, force_format: OutputFormat | null | undefined, layout_import: string | null | undefined, component_imports: any, self_path: string | null | undefined, markdown_only: boolean | null | undefined, clover_extensions: any): any;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly transform: (a: number, b: number, c: number, d: number, e: number, f: any, g: number, h: number, i: number, j: any) => any;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;