https://github.com/zooniverse/markdownz
Markdown viewer and editor for the zooniverse
https://github.com/zooniverse/markdownz
utility
Last synced: 4 months ago
JSON representation
Markdown viewer and editor for the zooniverse
- Host: GitHub
- URL: https://github.com/zooniverse/markdownz
- Owner: zooniverse
- License: apache-2.0
- Created: 2015-08-03T14:25:26.000Z (almost 11 years ago)
- Default Branch: main
- Last Pushed: 2025-09-12T14:15:18.000Z (9 months ago)
- Last Synced: 2025-11-14T07:23:45.737Z (7 months ago)
- Topics: utility
- Language: JavaScript
- Homepage:
- Size: 1.41 MB
- Stars: 2
- Watchers: 8
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# markdownz [](https://travis-ci.org/zooniverse/markdownz)
Markdown viewer, editor, and help components for the [Zooniverse](https://www.zooniverse.org). Requires React 16.8 or higher.
## Usage
Available on [npm](http://npmjs.com), 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`.
```jsx
import { Markdown } from 'markdownz';
{A String of `Markdown`}
```
Debug the viewer with the `debug` prop:
```jsx
import { Markdown } from 'markdownz';
{A String of `Markdown`}
```
Editor:
```jsx
import { MarkdownEditor } from 'markdownz';
```
Help:
```jsx
import { MarkdownHelp } from 'markdownz'
Guide to Markdown} />
```
Utilities:
```js
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 });
```
```jsx
// render HTML as JSX with utils.getComponentTree
import { utils } from 'markdownz';
const html = '
This is a test paragraph, with a link.';
const markdownChildren = utils.getComponentTree({ html });
return
{markdownChildren};
```
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`;
```jsx
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 `` in the Markdown editor |
| value | `''` | Value of the `` in the Markdown editor |
| placeholder | `''` | Placeholder text in the `` |
| row | `5` | Height of the `` |
| cols | `''` | `null` | Width of `` |
| 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 | `
Guide to using Markdown
` | Title displayed at the top of the MarkdownHelp component |
## Zooniverse-Flavoured Markdown
We use [markdown-it](https://github.com/markdown-it/markdown-it) for rendering Markdown and [twemoji](https://github.com/twitter/twemoji) for cross-browser emoji support.
TODO: Document custom extensions.
## Contributing
See [CONTRIBUTING.md](https://github.com/zooniverse/markdownz/tree/master/CONTRIBUTING.md)
## Publishing
1. Create a new branch for the new version.
2. Add the new version to the changelog with summary of changes.
3. Update package.json and package-lock.json with the new version number (manually or with `npm --no-git-tag-version version [major|minor|patch]`).
4. Commit and push the changes to GitHub. Create a pull request, optionally have it reviewed, and merge it.
5. Using GitHub's web interface, create a new tag and release with the new version number and summary of changes.
6. Pull the new version of the package locally.
7. To clear any prior build (`./lib`), run tests, and create a fresh build, run `"rm -rf lib && npm test && npm run build"`.
8. Run `npm publish --dry-run` to check that the package is ready to publish.
9. Run `npm publish` to publish the new version to npm.
## License
Copyright 2015 by The Zooniverse. Licensed under the Apache Public License v2. See [LICENSE](https://github.com/zooniverse/markdownz/tree/master/LICENSE) for details.