writr 4.4.6 → 4.5.1

package/README.md

@@ -9,7 +9,8 @@
 
 # Features
 * Removes the remark / unified complexity and easy to use.
-* Built in caching 💥 making it render very fast when there isnt a change
+* Powered by the [unified processor](https://github.com/unifiedjs/unified) for an extensible plugin pipeline.
+* Built in caching 💥 making it render very fast when there isn't a change
 * Frontmatter support built in by default. :tada:
 * Easily Render to `React` or `HTML`.
 * Generates a Table of Contents for your markdown files (remark-toc).
@@ -22,7 +23,17 @@
 * MDX Support (remark-mdx).
 * Built in Hooks for adding code to render pipeline.
 
+# Unified Processor Engine
+
+Writr builds on top of the open source [unified](https://github.com/unifiedjs/unified) processor – the core project that powers
+[remark](https://github.com/remarkjs/remark), [rehype](https://github.com/rehypejs/rehype), and many other content tools. Unified
+provides a pluggable pipeline where each plugin transforms a syntax tree. Writr configures a default set of plugins to turn
+Markdown into HTML, but you can access the processor through the `.engine` property to add your own behavior with
+`writr.engine.use(myPlugin)`. The [unified documentation](https://unifiedjs.com/) has more details and guides for building
+plugins and working with the processor directly.
+
 # Table of Contents
+- [Unified Processor Engine](#unified-processor-engine)
 - [Getting Started](#getting-started)
 - [API](#api)
   - [`new Writr(arg?: string | WritrOptions, options?: WritrOptions)`](#new-writrarg-string--writroptions-options-writroptions)
@@ -33,16 +44,18 @@
   - [`.frontMatterRaw`](#frontmatterraw)
   - [`.cache`](#cache)
   - [`.engine`](#engine)
-  - [`.render(options?: RenderOptions): Promise<string>`](#renderoptions-renderoptions-promisestring)
-  - [`.renderSync(options?: RenderOptions): string`](#rendersyncoptions-renderoptions-string)
-  - [`.renderToFile(filePath: string, options?: RenderOptions)`](#rendertofilefilepath-string-options-renderoptions)
-  - [`.renderToFileSync(filePath: string, options?: RenderOptions): void`](#rendertofilesyncfilepath-string-options-renderoptions-void)
-  - [`.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions): Promise<React.JSX.Element />`](#renderreactoptions-renderoptions-reactoptions-htmlreactparseroptions-promise-reactjsxelement-)
-  - [`.renderReactSync( options?: RenderOptions, reactOptions?: HTMLReactParserOptions): React.JSX.Element`](#renderreactsync-options-renderoptions-reactoptions-htmlreactparseroptions-reactjsxelement)
-  - [`.loadFromFile(filePath: string): Promise<void>`](#loadfromfilefilepath-string-promisevoid)
-  - [`.loadFromFileSync(filePath: string): void`](#loadfromfilesyncfilepath-string-void)
-  - [`.saveToFile(filePath: string): Promise<void>`](#savetofilefilepath-string-promisevoid)
-  - [`.saveToFileSync(filePath: string): void`](#savetofilesyncfilepath-string-void)
+  - [`.render(options?: RenderOptions)`](#renderoptions-renderoptions)
+  - [`.renderSync(options?: RenderOptions)`](#rendersyncoptions-renderoptions)
+  - [`.renderToFile(filePath: string, options?)`](#rendertofilefilepath-string-options-renderoptions)
+  - [`.renderToFileSync(filePath: string, options?)`](#rendertofilesyncfilepath-string-options-renderoptions)
+  - [`.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions)`](#renderreactoptions-renderoptions-reactoptions-htmlreactparseroptions)
+  - [`.renderReactSync( options?: RenderOptions, reactOptions?: HTMLReactParserOptions)`](#renderreactsync-options-renderoptions-reactoptions-htmlreactparseroptions)
+  - [`.validate(content?: string, options?: RenderOptions)`](#validatecontent-string-options-renderoptions)
+  - [`.validateSync(content?: string, options?: RenderOptions)`](#validatesynccontent-string-options-renderoptions)
+  - [`.loadFromFile(filePath: string)`](#loadfromfilefilepath-string)
+  - [`.loadFromFileSync(filePath: string)`](#loadfromfilesyncfilepath-string)
+  - [`.saveToFile(filePath: string)`](#savetofilefilepath-string)
+  - [`.saveToFileSync(filePath: string)`](#savetofilesyncfilepath-string)
 - [Hooks](#hooks)
 - [ESM and Node Version Support](#esm-and-node-version-support)
 - [Code of Conduct and Contributing](#code-of-conduct-and-contributing)
@@ -219,10 +232,10 @@ const html = await writr.render(options); // <h1>Hello World ::-):</h1><p>This i
 
 ## `.engine`
 
-Accessing the underlying engine for this instance of Writr. This is a `Processor<Root, Root, Root, undefined, undefined>` fro the unified `.use()` function. You can use this to add additional plugins to the engine. You can learn more about the unified engine [here](https://unifiedjs.com/) and a getting started guide [here](https://unifiedjs.com/learn/guide/using-unified/).
+Accessing the underlying engine for this instance of Writr. This is a `Processor<Root, Root, Root, undefined, undefined>` from the core [`unified`](https://github.com/unifiedjs/unified) project and uses the familiar `.use()` plugin pattern. You can chain additional unified plugins on this processor to customize the render pipeline. Learn more about the unified engine at [unifiedjs.com](https://unifiedjs.com/) and check out the [getting started guide](https://unifiedjs.com/learn/guide/using-unified/) for examples.
 
 
-## `.render(options?: RenderOptions): Promise<string>`
+## `.render(options?: RenderOptions)`
 
 Rendering markdown to HTML. the options are based on RenderOptions. Which you can access from the Writr instance.
 
@@ -239,7 +252,7 @@ const options  = {
 const html = await writr.render(options); // <h1>Hello World ::-):</h1><p>This is a test.</p>
 ```
 
-## `.renderSync(options?: RenderOptions): string`
+## `.renderSync(options?: RenderOptions)`
 
 Rendering markdown to HTML synchronously. the options are based on RenderOptions. Which you can access from the Writr instance. The parameters are the same as the `.render()` function.
 
@@ -249,7 +262,7 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 const html = writr.renderSync(); // <h1>Hello World 🙂</h1><p>This is a test.</p>
 ```
 
-## '.renderToFile(filePath: string, options?: RenderOptions)'
+## `.renderToFile(filePath: string, options?: RenderOptions)`
 
 Rendering markdown to a file. The options are based on RenderOptions.
 
@@ -259,7 +272,7 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 await writr.renderToFile('path/to/file.html');
 ```
 
-## '.renderToFileSync(filePath: string, options?: RenderOptions): void'
+## `.renderToFileSync(filePath: string, options?: RenderOptions)`
 
 Rendering markdown to a file synchronously. The options are based on RenderOptions.
 
@@ -269,7 +282,7 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 writr.renderToFileSync('path/to/file.html');
 ```
 
-## '.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions): Promise<React.JSX.Element />'
+## `.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions)`
 
 Rendering markdown to React. The options are based on RenderOptions and now HTMLReactParserOptions from `html-react-parser`.
 
@@ -279,7 +292,7 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 const reactElement = await writr.renderReact(); // Will return a React.JSX.Element
 ```
 
-## '.renderReactSync( options?: RenderOptions, reactOptions?: HTMLReactParserOptions): React.JSX.Element'
+## `.renderReactSync( options?: RenderOptions, reactOptions?: HTMLReactParserOptions)`
 
 Rendering markdown to React. The options are based on RenderOptions and now HTMLReactParserOptions from `html-react-parser`.
 
@@ -289,7 +302,51 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 const reactElement = writr.renderReactSync(); // Will return a React.JSX.Element
 ```
 
-## `.loadFromFile(filePath: string): Promise<void>`
+## `.validate(content?: string, options?: RenderOptions)`
+
+Validate markdown content by attempting to render it. Returns a `WritrValidateResult` object with a `valid` boolean and optional `error` property. Note that this will disable caching on render to ensure accurate validation.
+
+```javascript
+import { Writr } from 'writr';
+const writr = new Writr(`# Hello World\n\nThis is a test.`);
+
+// Validate current content
+const result = await writr.validate();
+console.log(result.valid); // true
+
+// Validate external content without changing the instance
+const externalResult = await writr.validate('## Different Content');
+console.log(externalResult.valid); // true
+console.log(writr.content); // Still "# Hello World\n\nThis is a test."
+
+// Handle validation errors
+const invalidWritr = new Writr('Put invalid markdown here');
+const errorResult = await invalidWritr.validate();
+console.log(errorResult.valid); // false
+console.log(errorResult.error?.message); // "Failed to render markdown: Invalid plugin"
+```
+
+## `.validateSync(content?: string, options?: RenderOptions)`
+
+Synchronously validate markdown content by attempting to render it. Returns a `WritrValidateResult` object with a `valid` boolean and optional `error` property.
+
+This is the synchronous version of `.validate()` with the same parameters and behavior.
+
+```javascript
+import { Writr } from 'writr';
+const writr = new Writr(`# Hello World\n\nThis is a test.`);
+
+// Validate current content synchronously
+const result = writr.validateSync();
+console.log(result.valid); // true
+
+// Validate external content without changing the instance
+const externalResult = writr.validateSync('## Different Content');
+console.log(externalResult.valid); // true
+console.log(writr.content); // Still "# Hello World\n\nThis is a test."
+```
+
+## `.loadFromFile(filePath: string)`
 
 Load your markdown content from a file path.
 
@@ -299,11 +356,17 @@ const writr = new Writr();
 await writr.loadFromFile('path/to/file.md');
 ```
 
-## `.loadFromFileSync(filePath: string): void`
+## `.loadFromFileSync(filePath: string)`
 
 Load your markdown content from a file path synchronously.
 
-## `.saveToFile(filePath: string): Promise<void>`
+```javascript
+import { Writr } from 'writr';
+const writr = new Writr();
+writr.loadFromFileSync('path/to/file.md');
+```
+
+## `.saveToFile(filePath: string)`
 
 Save your markdown and frontmatter (if included) content to a file path.
 
@@ -313,10 +376,16 @@ const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
 await writr.saveToFile('path/to/file.md');
 ```
 
-## `.saveToFileSync(filePath: string): void`
+## `.saveToFileSync(filePath: string)`
 
 Save your markdown and frontmatter (if included) content to a file path synchronously.
 
+```javascript
+import { Writr } from 'writr';
+const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
+writr.saveToFileSync('path/to/file.md');
+```
+
 # Caching On Render
 
 Caching is built into Writr and is an in-memory cache using `CacheableMemory` from [Cacheable](https://cacheable.org). It is turned off by default and can be enabled by setting `caching: true` in the `RenderOptions` of the `WritrOptions` or when calling render passing the `RenderOptions` like here:
@@ -409,10 +478,10 @@ This is called when you call `loadFromFile`, `loadFromFileSync`.
 
 # ESM and Node Version Support
 
-This package is ESM only and tested on the current lts version and its previous. Please don't open issues for questions regarding CommonJS / ESM or previous Nodejs versions. To learn more about using ESM please read this from `sindresorhus`: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+This package is ESM only and tested on the current lts version and its previous. Please don't open issues for questions regarding CommonJS / ESM or previous Nodejs versions.
 
 # Code of Conduct and Contributing
-[Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing](CONTRIBUTING.md) guidelines.
+Please use our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing](CONTRIBUTING.md) guidelines for development and testing. We appreciate your contributions!
 
 # License
 

package/dist/writr.d.ts

@@ -1,9 +1,9 @@
 import * as unified from 'unified';
 import * as hast from 'hast';
 import * as mdast from 'mdast';
-import React from 'react';
-import { HTMLReactParserOptions } from 'html-react-parser';
 import { Hookified } from 'hookified';
+import { HTMLReactParserOptions } from 'html-react-parser';
+import React from 'react';
 import { CacheableMemory } from 'cacheable';
 
 declare class WritrCache {
@@ -50,6 +50,16 @@ type RenderOptions = {
     mdx?: boolean;
     caching?: boolean;
 };
+/**
+ * Validation result.
+ * @typedef {Object} WritrValidateResult
+ * @property {boolean} valid - Whether the markdown is valid
+ * @property {Error} [error] - Error if validation failed
+ */
+type WritrValidateResult = {
+    valid: boolean;
+    error?: Error;
+};
 declare enum WritrHooks {
     beforeRender = "beforeRender",
     afterRender = "afterRender",
@@ -134,6 +144,20 @@ declare class Writr extends Hookified {
      * @returns {string} The rendered HTML content.
      */
     renderSync(options?: RenderOptions): string;
+    /**
+     * Validate the markdown content by attempting to render it.
+     * @param {string} [content] The markdown content to validate. If not provided, uses the current content.
+     * @param {RenderOptions} [options] The render options.
+     * @returns {Promise<WritrValidateResult>} An object with a valid boolean and optional error.
+     */
+    validate(content?: string, options?: RenderOptions): Promise<WritrValidateResult>;
+    /**
+     * Validate the markdown content by attempting to render it synchronously.
+     * @param {string} [content] The markdown content to validate. If not provided, uses the current content.
+     * @param {RenderOptions} [options] The render options.
+     * @returns {WritrValidateResult} An object with a valid boolean and optional error.
+     */
+    validateSync(content?: string, options?: RenderOptions): WritrValidateResult;
     /**
      * Render the markdown content and save it to a file. If the directory doesn't exist it will be created.
      * @param {string} filePath The file path to save the rendered markdown content to.
@@ -190,4 +214,4 @@ declare class Writr extends Hookified {
     private mergeRenderOptions;
 }
 
-export { type RenderOptions, Writr, WritrHooks, type WritrOptions };
+export { type RenderOptions, Writr, WritrHooks, type WritrOptions, type WritrValidateResult };

package/dist/writr.js

@@ -1,24 +1,24 @@
 // src/writr.ts
 import fs from "fs";
 import { dirname } from "path";
-import { unified } from "unified";
-import remarkParse from "remark-parse";
-import remarkRehype from "remark-rehype";
-import rehypeSlug from "rehype-slug";
+import { Hookified } from "hookified";
+import parse from "html-react-parser";
+import * as yaml from "js-yaml";
 import rehypeHighlight from "rehype-highlight";
-import rehypeStringify from "rehype-stringify";
-import remarkToc from "remark-toc";
-import remarkMath from "remark-math";
 import rehypeKatex from "rehype-katex";
-import remarkGfm from "remark-gfm";
+import rehypeSlug from "rehype-slug";
+import rehypeStringify from "rehype-stringify";
 import remarkEmoji from "remark-emoji";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
 import remarkMDX from "remark-mdx";
-import parse from "html-react-parser";
-import * as yaml from "js-yaml";
-import { Hookified } from "hookified";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import remarkToc from "remark-toc";
+import { unified } from "unified";
 
 // src/writr-cache.ts
-import { CacheableMemory, Cacheable } from "cacheable";
+import { Cacheable, CacheableMemory } from "cacheable";
 var WritrCache = class {
   _store = new CacheableMemory();
   _hashStore = new CacheableMemory();
@@ -142,23 +142,24 @@ var Writr = class extends Hookified {
     if (!this._content.trimStart().startsWith("---")) {
       return "";
     }
-    const start = this._content.indexOf("---\n");
-    const end = this._content.indexOf("\n---\n", start + 4);
-    if (end === -1) {
-      return "";
+    const match = /^\s*(---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$))/.exec(
+      this._content
+    );
+    if (match) {
+      return match[1];
     }
-    return this._content.slice(start, end + 5);
+    return "";
   }
   /**
    * Get the body content without the front matter.
    * @type {string} The markdown content without the front matter.
    */
   get body() {
-    if (this.frontMatterRaw === "") {
+    const frontMatter = this.frontMatterRaw;
+    if (frontMatter === "") {
       return this._content;
     }
-    const end = this._content.indexOf("\n---\n");
-    return this._content.slice(Math.max(0, end + 5)).trim();
+    return this._content.slice(this._content.indexOf(frontMatter) + frontMatter.length).trim();
   }
   /**
    * Get the markdown content. This is an alias for the body property.
@@ -171,6 +172,7 @@ var Writr = class extends Hookified {
    * Get the front matter content as an object.
    * @type {Record<string, any>} The front matter content as an object.
    */
+  // biome-ignore lint/suspicious/noExplicitAny: expected
   get frontMatter() {
     const frontMatter = this.frontMatterRaw;
     const match = /^---\s*([\s\S]*?)\s*---\s*/.exec(frontMatter);
@@ -187,6 +189,7 @@ var Writr = class extends Hookified {
    * Set the front matter content as an object.
    * @type {Record<string, any>} The front matter content as an object.
    */
+  // biome-ignore lint/suspicious/noExplicitAny: expected
   set frontMatter(data) {
     const frontMatter = this.frontMatterRaw;
     const yamlString = yaml.dump(data);
@@ -233,7 +236,11 @@ ${yamlString}---
       const file = await engine.process(renderData.body);
       resultData.result = String(file);
       if (this.isCacheEnabled(renderData.options)) {
-        this._cache.set(renderData.content, resultData.result, renderData.options);
+        this._cache.set(
+          renderData.content,
+          resultData.result,
+          renderData.options
+        );
       }
       await this.hook("afterRender" /* afterRender */, resultData);
       return resultData.result;
@@ -271,7 +278,11 @@ ${yamlString}---
       const file = engine.processSync(renderData.body);
       resultData.result = String(file);
       if (this.isCacheEnabled(renderData.options)) {
-        this._cache.set(renderData.content, resultData.result, renderData.options);
+        this._cache.set(
+          renderData.content,
+          resultData.result,
+          renderData.options
+        );
       }
       this.hook("afterRender" /* afterRender */, resultData);
       return resultData.result;
@@ -279,6 +290,72 @@ ${yamlString}---
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
   }
+  /**
+   * Validate the markdown content by attempting to render it.
+   * @param {string} [content] The markdown content to validate. If not provided, uses the current content.
+   * @param {RenderOptions} [options] The render options.
+   * @returns {Promise<WritrValidateResult>} An object with a valid boolean and optional error.
+   */
+  async validate(content, options) {
+    const originalContent = this._content;
+    try {
+      if (content !== void 0) {
+        this._content = content;
+      }
+      let { engine } = this;
+      if (options) {
+        options = {
+          ...this._options.renderOptions,
+          ...options,
+          caching: false
+        };
+        engine = this.createProcessor(options);
+      }
+      await engine.run(engine.parse(this.body));
+      if (content !== void 0) {
+        this._content = originalContent;
+      }
+      return { valid: true };
+    } catch (error) {
+      if (content !== void 0) {
+        this._content = originalContent;
+      }
+      return { valid: false, error };
+    }
+  }
+  /**
+   * Validate the markdown content by attempting to render it synchronously.
+   * @param {string} [content] The markdown content to validate. If not provided, uses the current content.
+   * @param {RenderOptions} [options] The render options.
+   * @returns {WritrValidateResult} An object with a valid boolean and optional error.
+   */
+  validateSync(content, options) {
+    const originalContent = this._content;
+    try {
+      if (content !== void 0) {
+        this._content = content;
+      }
+      let { engine } = this;
+      if (options) {
+        options = {
+          ...this._options.renderOptions,
+          ...options,
+          caching: false
+        };
+        engine = this.createProcessor(options);
+      }
+      engine.runSync(engine.parse(this.body));
+      if (content !== void 0) {
+        this._content = originalContent;
+      }
+      return { valid: true };
+    } catch (error) {
+      if (content !== void 0) {
+        this._content = originalContent;
+      }
+      return { valid: false, error };
+    }
+  }
   /**
    * Render the markdown content and save it to a file. If the directory doesn't exist it will be created.
    * @param {string} filePath The file path to save the rendered markdown content to.
@@ -438,6 +515,7 @@ ${yamlString}---
     }
     return this._options?.renderOptions?.caching ?? false;
   }
+  // biome-ignore lint/suspicious/noExplicitAny: expected unified processor
   createProcessor(options) {
     const processor = unified().use(remarkParse);
     if (options.gfm) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writr",
-  "version": "4.4.6",
+  "version": "4.5.1",
   "description": "Markdown Rendering Simplified",
   "type": "module",
   "main": "./dist/writr.js",
@@ -45,45 +45,47 @@
     "markdown-to-react"
   ],
   "scripts": {
-    "clean": "rimraf ./dist ./coverage ./node_modules ./package-lock.json ./yarn.lock ./site/README.md ./site/dist",
+    "clean": "rimraf ./dist ./coverage ./node_modules ./pnpm-lock.yaml ./site/README.md ./site/dist",
     "build": "rimraf ./dist && tsup src/writr.ts --format esm --dts --clean",
-    "prepare": "npm run build",
-    "test": "xo --fix && vitest run --coverage",
+    "prepare": "pnpm build",
+    "lint": "biome check --write --error-on-warnings",
+    "test": "pnpm lint && vitest run --coverage",
+    "test:ci": "biome check --error-on-warnings && vitest run --coverage",
     "website:build": "rimraf ./site/README.md ./site/dist && npx docula build -s ./site -o ./site/dist",
     "website:serve": "rimraf ./site/README.md ./site/dist && npx docula serve -s ./site -o ./site/dist"
   },
   "dependencies": {
-    "cacheable": "^1.10.3",
-    "hookified": "^1.11.0",
+    "cacheable": "^2.0.2",
+    "hookified": "^1.12.1",
     "html-react-parser": "^5.2.6",
     "js-yaml": "^4.1.0",
-    "react": "^19.1.0",
+    "react": "^19.1.1",
     "rehype-highlight": "^7.0.2",
     "rehype-katex": "^7.0.1",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
-    "remark-emoji": "^5.0.1",
+    "remark-emoji": "^5.0.2",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
-    "remark-mdx": "^3.1.0",
+    "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "remark-toc": "^9.0.0",
     "unified": "^11.0.5"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^24.1.0",
-    "@types/react": "^19.1.8",
+    "@types/node": "^24.5.2",
+    "@types/react": "^19.1.13",
     "@vitest/coverage-v8": "^3.2.4",
-    "docula": "^0.13.1",
+    "docula": "^0.30.0",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "typescript": "^5.9.2",
     "vitest": "^3.2.4",
-    "webpack": "^5.100.2",
-    "xo": "^1.2.1"
+    "webpack": "^5.101.3"
   },
   "xo": {
     "ignores": [