Markdownz NPM | npm.io

markdownz

Markdown viewer, editor, and help components for the Zooniverse. Requires React 16.8 or higher.

Usage

Available on npm, include as a dependency using npm install --save markdownz

This package contains three publicly accessible components: a Markdown viewer and a Markdown editor for Zooniverse-flavored Markdown, and a MarkdownHelp component.

Viewer:

Parse markdown to HTML with markdown-it, then render the result as a React component tree with rehype-react.

import { Markdown } from 'markdownz';

<Markdown>{A String of `Markdown`}</Markdown>

Debug the viewer with the debug prop:

import { Markdown } from 'markdownz';

<Markdown debug>{A String of `Markdown`}</Markdown>

Editor:

import { MarkdownEditor } from 'markdownz';

<MarkdownEditor rows={20} value="A String of `Markdown`" onChange={this.handleMarkdownChange} />

Help:

import { MarkdownHelp } from 'markdownz'

<MarkdownHelp talk={true} title={<h1>Guide to Markdown</h1>} />

Utilities:

import { utils } from 'markdownz';

const content = `
# A test document

This is a test [with a link](https://www.zooniverse.org).
`
const html = utils.getHTML({ content });

// render HTML as JSX with utils.getComponentTree
import { utils } from 'markdownz';
const html = '<p>This is a test paragraph, with <a href="https://www.zooniverse.org">a link.</a>';
const markdownChildren = utils.getComponentTree({ html });
return <div>{markdownChildren}</div>;

Hooks:

The useMarkdownz hook accepts the same props as the Markdown component. It returns the parsed content as a React component tree, which can be rendered as JSX or with React.createElement;

import { useMarkdownz } from 'markdownz';

const markdownChildren = useMarkdownz({ content: 'This is some markdown', debug: true });
return <>{markdownChildren}</>;

Supported Properties

Viewer

property	default	effect
children	`null`	Markdown String to Render
components	`null`	Rehype component mappings for the parsed output
content	`''`	Markdown String to Render used if `this.props.children` is null
debug	`false`	Return error messages, if true, for easier debugging
settings	`{}`	Rehype settings for the parsed output
tag	`div`	HTML tag to wrap markdown content with
className	`''`	css classes for the element
project	`null`	Panoptes project for links
baseURI	'null'	Set the base URI for building links
inline	`false`	Toggles rendering between `markdownIt.render` and `markdownIt.renderInline`

Editor

property	default	effect
name	`''`	Name for the `<textarea>` in the Markdown editor
value	`''`	Value of the `<textarea>` in the Markdown editor
placeholder	`''`	Placeholder text in the `<textarea>`
row	`5`	Height of the `<textarea>`
cols	`''`	`null`	Width of `<textarea>`
onChange	`NOOP`	Change listener
project	`null`	Panoptes project for links
baseURI	'null'	Set the base URI for building links
className	`''`	css classes for the element
helpText	`null`	String or Component for custom help text for the editor
onHelp	`NOOP`	Function to run when help button is clicked
previewing	false	Toggle the editor's preview mode

Help

property	default	effect
talk	`false`	Toggle the inclusion of Talk-specific Markdown help content
title	`<h1 className="markdown-editor-title">Guide to using Markdown</h1>`	Title displayed at the top of the MarkdownHelp component

Zooniverse-Flavoured Markdown

We use markdown-it for rendering Markdown and twemoji for cross-browser emoji support.

TODO: Document custom extensions.

Contributing

See CONTRIBUTING.md

Publishing

Add the new version to the changelog.
npm version major|minor|patch to test, build, push and publish a new version tag. https://github.com/zooniverse/markdownz/blob/a28604159282a20530c5e88625e0f4823485fa60/package.json#L17-L20
Publish a new tagged release on GitHub.