From 1821119e9c533d05211bd189e6afffd316f40c40 Mon Sep 17 00:00:00 2001 From: sandypockets Date: Sun, 17 Dec 2023 18:52:02 -0500 Subject: [PATCH] Fix: Update readme --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++------ package.json | 2 +- 2 files changed, 65 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c8ed9fb..c876549 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,4 @@ # `epic-remark` - -**Warning**: This package is still in development. It is not yet ready for production use. - `epic-remark` is a Markdown to HTML processor built on top of `remark`. It adds GitHub-flavoured markdown capabilities, alongside some handy must-have custom plugins. Use the all-in-one `processMarkdown` function to format your markdown into HTML, or import the custom plugins working behind the scenes one-by-one to mix your own flavour of Markdown HTML. @@ -20,15 +17,71 @@ All supported frameworks are available in the `examples/` directory. You can sti - `remark-rehype`: `^11.0.0` - `rehype-raw`: `^7.0.0` -## How does it work +## How it works `epic-remark` first uses `remark` and `remark-html` to convert your initial markdown to HTML. Then, `remark-gfm` is applied to enable the use of GitHub-flavoured markdown (tables, strikethrough, etc). At this point, the HTML is in a special `remark` AST (Abstract Syntax Tree). While it is possible to traverse and modify the tree, it can have some unexpected results. To create a more predictable environment, `epic-remark` uses `remark-rehype` to convert the `remark` AST to an easily adjustable HAST (HTML Abstract Syntax Tree). `epic-remark` then runs any of the custom `epic-remark` plugins you've enabled, serializes the newly modified HAST using `rehype-stringify`, and returns the HTML content back to you, ready to display on your frontend. +## Getting started +### Installation +Install `epic-remark` using npm: + +```bash +npm install epic-remark +``` + +or with yarn + +```bash +yarn add epic-remark +``` + +### Usage +To use `epic-remark` in your project, you can import the `processMarkdown` function and use it to convert Markdown into HTML. + +```javascript +import { processMarkdown } from 'epic-remark'; + +const markdown = `# Your Markdown Here`; +const html = processMarkdown(markdown); +``` + +### Configuration +processMarkdown accepts an optional options object, which allows you to configure various aspects of the Markdown processing. + +#### Basic Options +* `addHeadingIds`: `Boolean`. Automatically adds IDs to heading tags (h1 to h6). Defaults to false. +* `wrapConfig`: `Object`. Defines custom wrappers for specified HTML elements. Defaults to `{ img: 'epic-remark-image', table: 'epic-remark-table' }`. +* `addTableOfContents`: `Boolean`. Generates a table of contents based on headings. Defaults to false. +* `calculateReadingTime`: `Boolean`. Estimates the reading time of the content. Defaults to false. +* `wordsPerMinute`: `Number`. Defines the words-per-minute metric used to calculate reading time. Defaults to 250. +* `renderEmbeds`: `Boolean`. Embeds content from external sources like YouTube videos or GitHub gists. Defaults to false. + +#### Example with Options + +```javascript +import { processMarkdown } from 'epic-remark'; + +const markdown = `# Your Markdown Here`; + +const options = { + addHeadingIds: true, + wrapConfig: { img: 'custom-img-class' }, + addTableOfContents: true, + calculateReadingTime: true, + wordsPerMinute: 200, + renderEmbeds: true +}; + +const html = processMarkdown(markdown, options); +``` + +See the [documentation](DOCUMENTATION.md) for more details on each option. + # Plugins ## `processMarkdown` -The processMarkdown function is the core of epic-remark. It converts markdown to HTML, applying a range of configurable options to enable additional plugins during execution. It is the primary function you'll use, with other plugins augmenting its capabilities. +The processMarkdown function is the core of` epic-remark`. It converts markdown to HTML, applying a range of configurable options to enable additional plugins during execution. It is the primary function you'll use, with other plugins augmenting its capabilities. ## `addHeadingIds` Automatically adds an id attribute to all headings (h1 to h6). The id value mirrors the heading's text, transformed into a URL-friendly format. This plugin is ideal for creating anchor links and improving navigability within documents. @@ -43,13 +96,17 @@ Generates a table of contents based on the document's headings. Users can config Estimates the reading time of the provided markdown content. The calculation is based on a standard words-per-minute metric, which can be adjusted via options. The reading time is returned in minutes, offering a quick overview of the content length. ## `embed` -Embeds content from external sources, such as YouTube videos and GitHub gists with simple syntax like `!embed https://your-embed-url.com/` +Embeds content from external sources, such as YouTube videos and GitHub gists with simple syntax: + +```markdown +!embed https://your-embed-url.com/ +``` ### Notes Processed markdown always returns auto-linked URLs. This means that if you have a URL in your markdown, it will be converted to a clickable link. ## Contributing -Contributions are welcome! Please see the contributing docs for more details. +Contributions are welcome! Please see the [contributing guide](CONTRIBUTING.md) for more details. ## License `epic-remark` uses the MIT license. See [license.md](LICENSE.md) for more details. diff --git a/package.json b/package.json index 0c8b039..50619cf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "epic-remark", - "version": "0.2.2", + "version": "1.0.0", "description": "Epic Remark is an all-in-one markdown to HTML processor built on top of remark", "main": "dist/index.cjs.js", "module": "dist/index.esm.js",