writr 4.5.1 → 5.0.0

package/README.md

@@ -56,7 +56,18 @@ plugins and working with the processor directly.
   - [`.loadFromFileSync(filePath: string)`](#loadfromfilesyncfilepath-string)
   - [`.saveToFile(filePath: string)`](#savetofilefilepath-string)
   - [`.saveToFileSync(filePath: string)`](#savetofilesyncfilepath-string)
+- [Caching On Render](#caching-on-render)
+- [GitHub Flavored Markdown (GFM)](#github-flavored-markdown-gfm)
+  - [GFM Features](#gfm-features)
+  - [Using GFM](#using-gfm)
+  - [Disabling GFM](#disabling-gfm)
 - [Hooks](#hooks)
+- [Emitters](#emitters)
+  - [Error Events](#error-events)
+  - [Listening to Error Events](#listening-to-error-events)
+  - [Methods that Emit Errors](#methods-that-emit-errors)
+  - [Error Event Examples](#error-event-examples)
+  - [Event Emitter Methods](#event-emitter-methods)
 - [ESM and Node Version Support](#esm-and-node-version-support)
 - [Code of Conduct and Contributing](#code-of-conduct-and-contributing)
 - [License](#license)
@@ -413,6 +424,117 @@ writr.cache.store.lruSize = 100;
 writr.cache.store.ttl = '5m'; // setting it to 5 minutes
 ```
 
+# GitHub Flavored Markdown (GFM)
+
+Writr includes full support for [GitHub Flavored Markdown](https://github.github.com/gfm/) (GFM) through the `remark-gfm` and `remark-github-blockquote-alert` plugins. GFM is enabled by default and adds several powerful features to standard Markdown.
+
+## GFM Features
+
+When GFM is enabled (which it is by default), you get access to the following features:
+
+### Tables
+
+Create tables using pipes and hyphens:
+
+```markdown
+| Feature | Supported |
+|---------|-----------|
+| Tables  | Yes       |
+| Alerts  | Yes       |
+```
+
+### Strikethrough
+
+Use `~~` to create strikethrough text:
+
+```markdown
+~~This text is crossed out~~
+```
+
+### Task Lists
+
+Create interactive checkboxes:
+
+```markdown
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+### Autolinks
+
+URLs are automatically converted to clickable links:
+
+```markdown
+https://github.com
+```
+
+### GitHub Blockquote Alerts
+
+GitHub-style alerts are supported to emphasize critical information. These are blockquote-based admonitions that render with special styling:
+
+```markdown
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+## Using GFM
+
+GFM is enabled by default. Here's an example:
+
+```javascript
+import { Writr } from 'writr';
+
+const markdown = `
+# Task List Example
+
+- [x] Learn Writr basics
+- [ ] Master GFM features
+
+> [!NOTE]
+> GitHub Flavored Markdown is enabled by default!
+
+| Feature | Status |
+|---------|--------|
+| GFM     | ✓      |
+`;
+
+const writr = new Writr(markdown);
+const html = await writr.render(); // Renders with full GFM support
+```
+
+## Disabling GFM
+
+If you need to disable GFM features, you can set `gfm: false` in the render options:
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('~~strikethrough~~ text');
+
+// Disable GFM
+const html = await writr.render({ gfm: false });
+// Output: <p>~~strikethrough~~ text</p>
+
+// With GFM enabled (default)
+const htmlWithGfm = await writr.render({ gfm: true });
+// Output: <p><del>strikethrough</del> text</p>
+```
+
+Note: When GFM is disabled, GitHub blockquote alerts will not be processed and will render as regular blockquotes.
+
 # Hooks
 
 Hooks are a way to add additional parsing to the render pipeline. You can add hooks to the the Writr instance. Here is an example of adding a hook to the instance of Writr:
@@ -476,6 +598,135 @@ export type loadFromFileData = {
 
 This is called when you call `loadFromFile`, `loadFromFileSync`.
 
+# Emitters
+
+Writr extends the [Hookified](https://github.com/jaredwray/hookified) class, which provides event emitter capabilities. This means you can listen to events emitted by Writr during its lifecycle, particularly error events.
+
+## Error Events
+
+Writr emits an `error` event whenever an error occurs in any of its methods. This provides a centralized way to handle errors without wrapping every method call in a try/catch block.
+
+### Listening to Error Events
+
+You can listen to error events using the `.on()` method:
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('# Hello World');
+
+// Listen for any errors
+writr.on('error', (error) => {
+  console.error('An error occurred:', error.message);
+  // Handle the error appropriately
+  // Log to error tracking service, display to user, etc.
+});
+
+// Now when any error occurs, your listener will be notified
+try {
+  await writr.render();
+} catch (error) {
+  // Error is also thrown, so you can handle it here too
+}
+```
+
+### Methods that Emit Errors
+
+The following methods emit error events when they fail:
+
+**Rendering Methods:**
+- `render()` - Emits error before throwing when markdown rendering fails
+- `renderSync()` - Emits error before throwing when markdown rendering fails
+- `renderReact()` - Emits error before throwing when React rendering fails
+- `renderReactSync()` - Emits error before throwing when React rendering fails
+
+**Validation Methods:**
+- `validate()` - Emits error when validation fails (returns error in result object)
+- `validateSync()` - Emits error when validation fails (returns error in result object)
+
+**File Operations:**
+- `renderToFile()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+- `renderToFileSync()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+- `loadFromFile()` - Emits error when file reading fails (does not throw if `throwErrors: false`)
+- `loadFromFileSync()` - Emits error when file reading fails (does not throw if `throwErrors: false`)
+- `saveToFile()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+- `saveToFileSync()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
+
+**Front Matter Operations:**
+- `frontMatter` getter - Emits error when YAML parsing fails
+- `frontMatter` setter - Emits error when YAML serialization fails
+
+### Error Event Examples
+
+**Example 1: Global Error Handler**
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr();
+
+// Set up a global error handler
+writr.on('error', (error) => {
+  // Log to your monitoring service
+  console.error('Writr error:', error);
+
+  // Send to error tracking (e.g., Sentry, Rollbar)
+  // errorTracker.captureException(error);
+});
+
+// All errors will be emitted to the listener above
+await writr.loadFromFile('./content.md');
+const html = await writr.render();
+```
+
+**Example 2: Validation with Error Listening**
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('# My Content');
+let lastError = null;
+
+writr.on('error', (error) => {
+  lastError = error;
+});
+
+const result = await writr.validate();
+
+if (!result.valid) {
+  console.log('Validation failed');
+  console.log('Error details:', lastError);
+  // result.error is also available
+}
+```
+
+**Example 3: File Operations Without Try/Catch**
+
+```javascript
+import { Writr } from 'writr';
+
+const writr = new Writr('# Content', { throwErrors: false });
+
+writr.on('error', (error) => {
+  console.error('File operation failed:', error.message);
+  // Handle gracefully - maybe use default content
+});
+
+// Won't throw, but will emit error event if file doesn't exist
+await writr.loadFromFile('./maybe-missing.md');
+```
+
+### Event Emitter Methods
+
+Since Writr extends Hookified, you have access to standard event emitter methods:
+
+- `writr.on(event, handler)` - Add an event listener
+- `writr.once(event, handler)` - Add a one-time event listener
+- `writr.off(event, handler)` - Remove an event listener
+- `writr.emit(event, data)` - Emit an event (used internally)
+
+For more information about event handling capabilities, see the [Hookified documentation](https://github.com/jaredwray/hookified).
+
 # 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.

package/dist/writr.d.ts

@@ -37,8 +37,8 @@ type WritrOptions = {
  * @property {boolean} [highlight] - Code highlighting (default: true)
  * @property {boolean} [gfm] - Github flavor markdown (default: true)
  * @property {boolean} [math] - Math support (default: true)
- * @property {boolean} [mdx] - MDX support (default: true)
- * @property {boolean} [caching] - Caching (default: false)
+ * @property {boolean} [mdx] - MDX support (default: false)
+ * @property {boolean} [caching] - Caching (default: true)
  */
 type RenderOptions = {
     emoji?: boolean;

package/dist/writr.js

@@ -10,6 +10,7 @@ import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
 import remarkEmoji from "remark-emoji";
 import remarkGfm from "remark-gfm";
+import remarkGithubBlockquoteAlert from "remark-github-blockquote-alert";
 import remarkMath from "remark-math";
 import remarkMDX from "remark-mdx";
 import remarkParse from "remark-parse";
@@ -64,7 +65,7 @@ var WritrHooks = /* @__PURE__ */ ((WritrHooks2) => {
   return WritrHooks2;
 })(WritrHooks || {});
 var Writr = class extends Hookified {
-  engine = unified().use(remarkParse).use(remarkGfm).use(remarkToc).use(remarkEmoji).use(remarkRehype).use(rehypeSlug).use(remarkMath).use(rehypeKatex).use(rehypeHighlight).use(remarkMDX).use(rehypeStringify);
+  engine = unified().use(remarkParse).use(remarkGfm).use(remarkToc).use(remarkEmoji).use(remarkRehype).use(rehypeSlug).use(remarkMath).use(rehypeKatex).use(rehypeHighlight).use(rehypeStringify);
   // Stringify HTML
   _options = {
     throwErrors: false,
@@ -75,8 +76,8 @@ var Writr = class extends Hookified {
       highlight: true,
       gfm: true,
       math: true,
-      mdx: true,
-      caching: false
+      mdx: false,
+      caching: true
     }
   };
   _content = "";
@@ -191,12 +192,16 @@ var Writr = class extends Hookified {
    */
   // biome-ignore lint/suspicious/noExplicitAny: expected
   set frontMatter(data) {
-    const frontMatter = this.frontMatterRaw;
-    const yamlString = yaml.dump(data);
-    const newFrontMatter = `---
+    try {
+      const frontMatter = this.frontMatterRaw;
+      const yamlString = yaml.dump(data);
+      const newFrontMatter = `---
 ${yamlString}---
 `;
-    this._content = this._content.replace(frontMatter, newFrontMatter);
+      this._content = this._content.replace(frontMatter, newFrontMatter);
+    } catch (error) {
+      this.emit("error", error);
+    }
   }
   /**
    * Get the front matter value for a key.
@@ -245,6 +250,7 @@ ${yamlString}---
       await this.hook("afterRender" /* afterRender */, resultData);
       return resultData.result;
     } catch (error) {
+      this.emit("error", error);
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
   }
@@ -287,6 +293,7 @@ ${yamlString}---
       this.hook("afterRender" /* afterRender */, resultData);
       return resultData.result;
     } catch (error) {
+      this.emit("error", error);
       throw new Error(`Failed to render markdown: ${error.message}`);
     }
   }
@@ -317,6 +324,7 @@ ${yamlString}---
       }
       return { valid: true };
     } catch (error) {
+      this.emit("error", error);
       if (content !== void 0) {
         this._content = originalContent;
       }
@@ -350,6 +358,7 @@ ${yamlString}---
       }
       return { valid: true };
     } catch (error) {
+      this.emit("error", error);
       if (content !== void 0) {
         this._content = originalContent;
       }
@@ -410,8 +419,13 @@ ${yamlString}---
    * @returns {Promise<string | React.JSX.Element | React.JSX.Element[]>} The rendered React content.
    */
   async renderReact(options, reactParseOptions) {
-    const html = await this.render(options);
-    return parse(html, reactParseOptions);
+    try {
+      const html = await this.render(options);
+      return parse(html, reactParseOptions);
+    } catch (error) {
+      this.emit("error", error);
+      throw new Error(`Failed to render React: ${error.message}`);
+    }
   }
   /**
    * Render the markdown content to React synchronously.
@@ -420,8 +434,13 @@ ${yamlString}---
    * @returns {string | React.JSX.Element | React.JSX.Element[]} The rendered React content.
    */
   renderReactSync(options, reactParseOptions) {
-    const html = this.renderSync(options);
-    return parse(html, reactParseOptions);
+    try {
+      const html = this.renderSync(options);
+      return parse(html, reactParseOptions);
+    } catch (error) {
+      this.emit("error", error);
+      throw new Error(`Failed to render React: ${error.message}`);
+    }
   }
   /**
    * Load markdown content from a file.
@@ -520,6 +539,7 @@ ${yamlString}---
     const processor = unified().use(remarkParse);
     if (options.gfm) {
       processor.use(remarkGfm);
+      processor.use(remarkGithubBlockquoteAlert);
     }
     if (options.toc) {
       processor.use(remarkToc, { heading: "toc|table of contents" });
@@ -585,3 +605,4 @@ export {
   Writr,
   WritrHooks
 };
+/* v8 ignore next -- @preserve */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writr",
-  "version": "4.5.1",
+  "version": "5.0.0",
   "description": "Markdown Rendering Simplified",
   "type": "module",
   "main": "./dist/writr.js",
@@ -55,17 +55,18 @@
     "website:serve": "rimraf ./site/README.md ./site/dist && npx docula serve -s ./site -o ./site/dist"
   },
   "dependencies": {
-    "cacheable": "^2.0.2",
-    "hookified": "^1.12.1",
-    "html-react-parser": "^5.2.6",
+    "cacheable": "^2.1.1",
+    "hookified": "^1.12.2",
+    "html-react-parser": "^5.2.7",
     "js-yaml": "^4.1.0",
-    "react": "^19.1.1",
+    "react": "^19.2.0",
     "rehype-highlight": "^7.0.2",
     "rehype-katex": "^7.0.1",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-emoji": "^5.0.2",
     "remark-gfm": "^4.0.1",
+    "remark-github-blockquote-alert": "^2.0.0",
     "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
@@ -74,23 +75,17 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.2.4",
+    "@biomejs/biome": "^2.3.1",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^24.5.2",
-    "@types/react": "^19.1.13",
-    "@vitest/coverage-v8": "^3.2.4",
-    "docula": "^0.30.0",
+    "@types/node": "^24.9.1",
+    "@types/react": "^19.2.2",
+    "@vitest/coverage-v8": "^4.0.4",
+    "docula": "^0.31.0",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4",
-    "webpack": "^5.101.3"
-  },
-  "xo": {
-    "ignores": [
-      "docula.config.*"
-    ]
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.4"
   },
   "files": [
     "dist",