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`
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

Create a new branch for the new version.
Add the new version to the changelog with summary of changes.
Update package.json and package-lock.json with the new version number (manually or with npm --no-git-tag-version version [major|minor|patch]).
Commit and push the changes to GitHub. Create a pull request, optionally have it reviewed, and merge it.
Using GitHub's web interface, create a new tag and release with the new version number and summary of changes.
Pull the new version of the package locally.
To clear any prior build (./lib), run tests, and create a fresh build, run "rm -rf lib && npm test && npm run build".
Run npm publish --dry-run to check that the package is ready to publish.
Run npm publish to publish the new version to npm.

eatyourgreens / markdownz