Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jaredwray/writr
Markdown Rendering Simplified
https://github.com/jaredwray/writr
emoji github-flavored-markdown highlighting html markdown markdown-processor markdown-to-html remark renderer syntax table-of-contents toc
Last synced: about 1 month ago
JSON representation
Markdown Rendering Simplified
- Host: GitHub
- URL: https://github.com/jaredwray/writr
- Owner: jaredwray
- License: mit
- Created: 2018-05-01T05:04:51.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-03-30T16:28:32.000Z (8 months ago)
- Last Synced: 2024-03-31T16:34:56.632Z (8 months ago)
- Topics: emoji, github-flavored-markdown, highlighting, html, markdown, markdown-processor, markdown-to-html, remark, renderer, syntax, table-of-contents, toc
- Language: TypeScript
- Homepage: https://writr.org
- Size: 1.34 MB
- Stars: 7
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
---
## Markdown Rendering Simplified
[](https://github.com/jaredwray/writr/actions/workflows/tests.yml)
[](https://github.com/jaredwray/writr/blob/master/LICENSE)
[](https://codecov.io/gh/jaredwray/writr)
[](https://npmjs.com/package/writr)
[](https://npmjs.com/package/writr)
---
## Table of Contents
- [Features](#features)
- [Getting Started](#getting-started)
- [License - MIT](#license)
## Features
* Removes the remark / unified complexity and easy to use.
* Built in caching 💥 making it render very fast when there isnt 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).
* Slug generation for your markdown files (rehype-slug).
* Code Highlighting (rehype-highlight).
* Math Support (rehype-katex).
* Markdown to HTML (rehype-stringify).
* Github Flavor Markdown (remark-gfm).
* Emoji Support (remark-emoji).
* MDX Support (remark-mdx).
## 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
## Getting Started
```bash
> npm install writr
```
Then you can use it like this:
```javascript
import { Writr } from 'writr';
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
const html = await writr.render(); //
Hello World 🙂
This is a test.
```
Its just that simple. Want to add some options? No problem.
```javascript
import { Writr } from 'writr';
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
const options = {
emoji: false
}
const html = await writr.render(options); //
Hello World ::-):
This is a test.
```
An example passing in the options also via the constructor:
```javascript
import { Writr, WritrOptions } from 'writr';
const writrOptions = {
renderOptions: {
emoji: true,
toc: true,
slug: true,
highlight: true,
gfm: true,
math: true,
mdx: true,
caching: true,
}
};
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`, writrOptions);
const html = await writr.render(options); //
Hello World ::-):
This is a test.
```
## API
### `new Writr(arg?: string | WritrOptions, options?: WritrOptions)`
By default the constructor takes in a markdown `string` or `WritrOptions` in the first parameter. You can also send in nothing and set the markdown via `.content` property. If you want to pass in your markdown and options you can easily do this with `new Writr('## Your Markdown Here', { ...options here})`. You can access the `WritrOptions` from the instance of Writr. Here is an example of WritrOptions.
```javascript
import { Writr, WritrOptions } from 'writr';
const writrOptions = {
renderOptions: {
emoji: true,
toc: true,
slug: true,
highlight: true,
gfm: true,
math: true,
mdx: true,
caching: true,
}
};
const writr = new Writr(writrOptions);
```
### `.content`
Setting the markdown content for the instance of Writr. This can be set via the constructor or directly on the instance and can even handle `frontmatter`.
```javascript
import { Writr } from 'writr';
const writr = new Writr();
writr.content = `---
title: Hello World
---
# Hello World ::-):\n\n This is a test.`;
```
### `.options`
Accessing the default options for this instance of Writr.
### `.cache`
Accessing the cache for this instance of Writr. By default this is an in memory cache and is enabled by default. You can disable this by setting `caching: false` in the `RenderOptions` of the `WritrOptions` or when calling render passing the `RenderOptions` like here:
```javascript
import { Writr } from 'writr';
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
const options = {
caching: false
}
const html = await writr.render(options); //
Hello World ::-):
This is a test.
```
If you would like to use a specific storage adapter from https://keyv.org you can pass in the adapter like so:
```javascript
import { Writr } from 'writr';
import Keyv from '@keyv/redis';
const keyvRedis = new Keyv('redis://user:pass@localhost:6379');
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
writr.cache.setStorageAdapter(keyvRedis);
```
### `.engine`
Accessing the underlying engine for this instance of Writr. This is a `Processor` fro the unified `.use()` function. You can use this to add additional plugins to the engine.
### `.render(options?: RenderOptions): Promise`
Rendering markdown to HTML. the options are based on RenderOptions. Which you can access from the Writr instance.
```javascript
import { Writr, RenderOptions } from 'writr';
## `RenderOptions`
```js
type RenderOptions = {
emoji?: boolean; // Emoji support (default: true)
toc?: boolean; // Table of contents generation (default: true)
slug?: boolean; // Slug generation (default: true)
highlight?: boolean; // Code highlighting (default: true)
gfm?: boolean; // Github flavor markdown (default: true)
math?: boolean; // Math support (default: true)
mdx?: boolean; // MDX support (default: true)
caching?: boolean; // Caching (default: true)
};
```
### `.renderSync(options?: RenderOptions): string`
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.
```javascript
import { Writr } from 'writr';
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
const html = writr.renderSync(); //
Hello World 🙂
This is a test.
```
### '.renderReact(options?: RenderOptions, reactOptions?: HTMLReactParserOptions): Promise'
Rendering markdown to React. The options are based on RenderOptions and now HTMLReactParserOptions from `html-react-parser`.
```javascript
import { Writr } from 'writr';
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'
Rendering markdown to React. The options are based on RenderOptions and now HTMLReactParserOptions from `html-react-parser`.
```javascript
import { Writr } from 'writr';
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`
Load your markdown content from a file path.
```javascript
import { Writr } from 'writr';
const writr = new Writr();
await writr.loadFromFile('path/to/file.md');
```
### `.loadFromFileSync(filePath: string): void`
Load your markdown content from a file path synchronously.
### `.saveToFile(filePath: string): Promise`
Save your markdown and frontmatter (if included) content to a file path.
```javascript
import { Writr } from 'writr';
const writr = new Writr(`# Hello World ::-):\n\n This is a test.`);
await writr.saveToFile('path/to/file.md');
```
### `.saveToFileSync(filePath: string): void`
Save your markdown and frontmatter (if included) content to a file path synchronously.
## Code of Conduct and Contributing
[Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing](CONTRIBUTING.md) guidelines.
## License
MIT © [Jared Wray](https://jaredwray.com)