@paperclover/markodown 1.0.0-rc.8 → 1.0.0

package/README.md

@@ -1,19 +1,18 @@
 # 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.
 
+Markodown is used in production for
+[my blog posts on paperclover.net](https://paperclover.net), where I ported my
+posts from MDX to it.
+
 [Markdown]: https://en.wikipedia.org/wiki/Markdown
 [Marko]: https://markojs.com/
 
-> **CONTENTS**:
->
 > - [Usage](#usage)
 >   - [Components](#components)
 >   - [Outline / Table of Contents](#outline-table-of-contents)
@@ -24,7 +23,7 @@ leveraging the existing ecosystem.
 > - [Config](#config)
 >   - [Frontmatter Layout Configuration](#frontmatter-layout-configuration)
 
-Here's a glance at how things look. Complete example documents in <./examples>
+Here's a glance at how things look. Complete example documents in `examples`.
 
 ````
 ---
@@ -271,21 +270,22 @@ import { Heading } from "@clo/markodown";
 
 export interface Input {
   content: Marko.Body;
-  
-  /** Markdown scans for headings (h1..h6) */
+  // 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. */
+  // 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>
+  <ul>
+    <for|heading| of=input.outline>
+      // heading content includes formatting, even custom tags.
+      <li><a href=`#${heading.id}`><${heading.content}/></a></li>
+    </for>
+  </ul>
 </aside>
 
 <${input.content} />

package/_dist/mod.d.ts

@@ -1,6 +1,30 @@
-type Transformed = Success | Failure;
-export interface TransformOptions {
-  source: string;
+/** 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
@@ -18,13 +42,14 @@ export interface TransformOptions {
    */ markdownOnly?: boolean;
   /**
    * These extensions are special-cased so that Clover can re-use this on
-   * her website without
+   * 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 markdown links with this import. */ link?: string;
+  /** Replace links with this import. */ link?: string;
   /** Replace images with this import. */ image?: string;
   /** Replace blockquotes with this import. */ blockquote?: string;
 }
@@ -36,6 +61,8 @@ export interface TransformOptions {
  * 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.
@@ -59,36 +86,54 @@ export interface TransformOptions {
    * `#name#` -> `<labelledRedaction>name</labelledRedaction>`
    */ labelledRedaction: string;
 }
-export type OutputFormat = "marko" | "html";
-export interface Success {
-  success: true;
-  text: string;
-  errors: [];
-  format: OutputFormat;
+/** 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: [];
 }
-export interface Failure {
-  success: false;
-  text: null;
-  errors: TransformError[];
-  outline: Heading[] | null;
+/** 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[]];
 }
-export interface Heading {
-  level: 1 | 2 | 3 | 4 | 5 | 6;
-  id: string;
-  // @ts-ignore fails if marko types not chilling
+/** 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 {
-  message: string;
-  labels: LabelledSpan[];
-  line: number;
-  column: number;
+  /** 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 LabelledSpan {
-  message: string;
-  line: number;
-  column: number;
-  width: 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;
 }
-export declare function transform(options: TransformOptions): Transformed;
 //# sourceMappingURL=mod.d.ts.map

package/_dist/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"KAKK,cAAc,UAAU;AAE7B,iBAAiB;EACf,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;;;GAGC,GACD,mBAAmB;;AAGrB,8BAA8B,GAC9B,iBAAiB;EACf,0EAA0E,GAC1E,UAAU,MAAM;EAChB,2CAA2C,GAC3C,YAAY,MAAM;EAClB,6CAA6C,GAC7C,OAAO,MAAM;EACb,qCAAqC,GACrC,QAAQ,MAAM;EACd,0CAA0C,GAC1C,aAAa,MAAM;;AAGrB;;;;;;;;CAQC,GACD,iBAAiB;EACf;;;;;;GAMC,GACD,UAAU,MAAM;EAChB;;;GAGC,GACD,aAAa,MAAM;EACnB;;;;;GAKC,GACD,aAAa,MAAM;EACnB;;;GAGC,GACD,mBAAmB,MAAM;;AAG3B,YAAY,eAAe,UAAU;AAErC,iBAAiB;EACf,SAAS,IAAI;EACb,MAAM,MAAM;EACZ;EACA,QAAQ;;AAGV,iBAAiB;EACf,SAAS,KAAK;EACd,MAAM,IAAI;EACV,QAAQ;EACR,SAAS,YAAY,IAAI;;AAG3B,iBAAiB;EACf,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI;EAC3B,IAAI,MAAM;EACV,+CAA+C;EAC/C,SAAS,MAAM;;AAGjB,iBAAiB;EACf,SAAS,MAAM;EACf,QAAQ;EACR,MAAM,MAAM;EACZ,QAAQ,MAAM;;AAGhB,iBAAiB;EACf,SAAS,MAAM;EACf,MAAM,MAAM;EACZ,QAAQ,MAAM;EACd,OAAO,MAAM;;AAGf,OAAO,iBAAS,UAAU,SAAS,gBAAgB,GAAG"}
+{"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"}