Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Markdown Format / Editor documentation + features #3696

Merged
merged 19 commits into from
Jul 28, 2020
Merged
Changes from 11 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions src-docs/src/routes.js
Original file line number Diff line number Diff line change
@@ -135,6 +135,10 @@ import { LoadingExample } from './views/loading/loading_example';

import { MarkdownEditorExample } from './views/markdown_editor/mardown_editor_example';

import { MarkdownFormatExample } from './views/markdown_editor/mardown_format_example';

import { MarkdownPluginExample } from './views/markdown_editor/markdown_plugin_example';

import { ModalExample } from './views/modal/modal_example';

import { MutationObserverExample } from './views/mutation_observer/mutation_observer_example';
@@ -366,7 +370,6 @@ const navigation = [
BadgeExample,
CallOutExample,
CardExample,
CodeExample,
CommentListExample,
DescriptionListExample,
DragAndDropExample,
@@ -396,18 +399,26 @@ const navigation = [
SuperSelectExample,
ComboBoxExample,
ColorPickerExample,
CodeEditorExample,
DatePickerExample,
ExpressionExample,
FilterGroupExample,
MarkdownEditorExample,
RangeControlExample,
SearchBarExample,
SelectableExample,
SuggestExample,
SuperDatePickerExample,
].map(example => createExample(example)),
},
{
name: 'Editors & syntax',
items: [
MarkdownFormatExample,
MarkdownEditorExample,
MarkdownPluginExample,
CodeEditorExample,
CodeExample,
].map(example => createExample(example)),
},
{
name: 'Elastic Charts',
items: [
68 changes: 63 additions & 5 deletions src-docs/src/views/markdown_editor/mardown_editor_example.js
Original file line number Diff line number Diff line change
@@ -1,17 +1,47 @@
import React from 'react';
import React, { Fragment } from 'react';

import { renderToHtml } from '../../services';

import { GuideSectionTypes } from '../../components';

import { EuiMarkdownEditor } from '../../../../src/components';
import {
EuiMarkdownEditor,
EuiText,
EuiSpacer,
EuiCode,
} from '../../../../src/components';

import { Link } from 'react-router-dom';

import MarkdownEditor from './markdown_editor';
const markdownEditorSource = require('!!raw-loader!./markdown_editor');
const markdownEditorHtml = renderToHtml(MarkdownEditor);

import MarkdownEditorErrors from './markdown_editor_errors';
const markdownEditorErrorsSource = require('!!raw-loader!./markdown_editor_errors');
const markdownEditorErrorsHtml = renderToHtml(MarkdownEditorErrors);

export const MarkdownEditorExample = {
title: 'Markdown Editor',
title: 'Markdown editor',
intro: (
<Fragment>
<EuiText>
<p>
<strong>EuiMarkdownEditor</strong> provides a markdown authoring
experience for the user. The component consists of a toolbar, text
area, and a drag-and-drop zone to accept files. There are two modes: a
chandlerprall marked this conversation as resolved.
Show resolved Hide resolved
textarea that keeps track of cursor position, and a rendered preview
mode that is powered by{' '}
<strong>
<Link to="/editors-syntax/markdown-format/">EuiMarkdownFormat</Link>
</strong>
. State is maintained between the two and it is possible to pass
changes from the preview area to the text area and vice versa.
snide marked this conversation as resolved.
Show resolved Hide resolved
</p>
</EuiText>
<EuiSpacer size="xxl" />
</Fragment>
),
sections: [
{
source: [
@@ -24,16 +54,44 @@ export const MarkdownEditorExample = {
code: markdownEditorHtml,
},
],
title: 'Base editor',
text: (
<p>
This component renders a markdown editor, including buttons for
quickly inserting common markdown elements and a preview mode.
The base editor can render basic markdown along with some built-in
plugins.
</p>
),
props: {
EuiMarkdownEditor,
},
demo: <MarkdownEditor />,
},
{
source: [
{
type: GuideSectionTypes.JS,
code: markdownEditorErrorsSource,
},
{
type: GuideSectionTypes.HTML,
code: markdownEditorErrorsHtml,
},
],
title: 'Error handling and feedback',
text: (
<p>
The <EuiCode>errors</EuiCode> prop allows you to pass an array of
errors if syntax is malformed. Below the tooltip plugin is able to
chandlerprall marked this conversation as resolved.
Show resolved Hide resolved
provide this message by default. These errors are meant to be
emphemeral and part of the editing experience. They should not be a
snide marked this conversation as resolved.
Show resolved Hide resolved
substitute for{' '}
<Link to="/forms/form-validation">form validation</Link>.
</p>
),
props: {
EuiMarkdownEditor,
},
demo: <MarkdownEditorErrors />,
},
],
};
94 changes: 94 additions & 0 deletions src-docs/src/views/markdown_editor/mardown_format_example.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
import React, { Fragment } from 'react';

import { renderToHtml } from '../../services';

import { GuideSectionTypes } from '../../components';

import {
EuiMarkdownFormat,
EuiText,
EuiSpacer,
} from '../../../../src/components';

import { Link } from 'react-router-dom';

import MarkdownFormat from './markdown_format';
const markdownFormatSource = require('!!raw-loader!./markdown_format');
const markdownFormatHtml = renderToHtml(MarkdownFormat);

import MarkdownFormatSink from './markdown_format_sink';
const markdownFormatSinkSource = require('!!raw-loader!./markdown_format_sink');
const markdownFormatSinkHtml = renderToHtml(MarkdownFormatSink);

export const MarkdownFormatExample = {
title: 'Markdown format',
intro: (
<Fragment>
<EuiText>
<p>
<strong>EuiMarkdownFormat</strong> is a read-only way to render
markdown-style content in a page. It is a peer component to{' '}
<strong>
<Link to="/editors-syntax/markdown-editor/">EuiMarkdownEditor</Link>
</strong>{' '}
and has the ability to be modified by additional{' '}
<Link to="/editors-syntax/markdown-plugins">markdown plugins</Link>.
</p>
</EuiText>
<EuiSpacer size="xxl" />
</Fragment>
),
sections: [
{
source: [
{
type: GuideSectionTypes.JS,
code: markdownFormatSource,
},
{
type: GuideSectionTypes.HTML,
code: markdownFormatHtml,
},
],
title: 'Built in plugins',
text: (
<p>
<strong>EuiMarkdownFormat</strong> is a wrapper that will render
Markdown provided. EuiMarkdownFormat uses{' '}
<Link to="https://github.com/remarkjs/remark)">Remark</Link> by
default. The translation layer automatically substitutes raw HTML
output with their EUI equivilant. This means anchor and code blocks
will become <strong>EuiLink</strong> and <strong>EuiCodeBlock</strong>{' '}
components respectively.
</p>
),
props: {
EuiMarkdownFormat,
},
demo: <MarkdownFormat />,
},
{
source: [
{
type: GuideSectionTypes.JS,
code: markdownFormatSinkSource,
},
{
type: GuideSectionTypes.HTML,
code: markdownFormatSinkHtml,
},
],
title: 'Kitchen sink',
text: (
<p>
This example shows of all the styling and markup possibilities. It is
mostly used for testing.
</p>
),
props: {
EuiMarkdownFormat,
},
demo: <MarkdownFormatSink />,
},
],
};
23 changes: 10 additions & 13 deletions src-docs/src/views/markdown_editor/markdown_editor.js
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
import React, { useCallback, useState } from 'react';

import {
defaultParsingPlugins,
defaultProcessingPlugins,
EuiMarkdownEditor,
EuiSpacer,
EuiCodeBlock,
EuiButtonToggle,
} from '../../../../src';
import * as MarkdownChart from './plugins/markdown_chart';
} from '../../../../src/components';

const markdownExample = require('!!raw-loader!./markdown-example.md');
const initialContent = `## Hello world!

const exampleParsingList = [...defaultParsingPlugins, MarkdownChart.parser];
Basic "github flavored" markdown will work as you'd expect.

const exampleProcessingList = [...defaultProcessingPlugins]; // pretend mutation doesn't happen immediately next 😅
exampleProcessingList[0][1].handlers.chartDemoPlugin = MarkdownChart.handler;
exampleProcessingList[1][1].components.chartDemoPlugin = MarkdownChart.renderer;
The editor also ships with some built in plugins. For example it can handle checkboxes. Notice how they toggle state even in the preview mode.

- [ ] Checkboxes
- [x] Can be filled
- [ ] Or empty
`;

export default () => {
const [value, setValue] = useState(markdownExample);
const [value, setValue] = useState(initialContent);
const [messages, setMessages] = useState([]);
const [ast, setAst] = useState(null);
const [isAstShowing, setIsAstShowing] = useState(false);
@@ -34,9 +34,6 @@ export default () => {
value={value}
onChange={setValue}
height={400}
uiPlugins={[MarkdownChart.plugin]}
parsingPluginList={exampleParsingList}
processingPluginList={exampleProcessingList}
onParse={onParse}
errors={messages}
/>
63 changes: 63 additions & 0 deletions src-docs/src/views/markdown_editor/markdown_editor_errors.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
import React, { useCallback, useState } from 'react';

import { Link } from 'react-router-dom';

import {
EuiMarkdownEditor,
EuiSpacer,
EuiCodeBlock,
EuiButtonToggle,
EuiFormErrorText,
} from '../../../../src/components';

const initialContent = `## Errors

The tooltip is empty and will error

!{tooltip[]()}
`;

export default () => {
const [value, setValue] = useState(initialContent);
const [messages, setMessages] = useState([]);
const [ast, setAst] = useState(null);
const [isAstShowing, setIsAstShowing] = useState(false);
const onParse = useCallback((err, { messages, ast }) => {
setMessages(err ? [err] : messages);
setAst(JSON.stringify(ast, null, 2));
}, []);
return (
<>
<EuiMarkdownEditor
aria-label="EUI markdown editor demo"
value={value}
onChange={setValue}
height={400}
onParse={onParse}
errors={messages}
/>
<EuiSpacer size="s" />

<EuiFormErrorText id="error" className="euiFormRow__text">
Utilize error text or{' '}
<strong>
<Link to="/forms/form-validation">EuiFormRow</Link>
</strong>{' '}
for more permanent error feedback
</EuiFormErrorText>

<div className="eui-textRight">
<EuiButtonToggle
label={isAstShowing ? 'Hide editor AST' : 'Show editor AST'}
size="s"
isEmpty
iconType={isAstShowing ? 'eyeClosed' : 'eye'}
onChange={() => setIsAstShowing(!isAstShowing)}
isSelected={isAstShowing}
/>
</div>

{isAstShowing && <EuiCodeBlock language="json">{ast}</EuiCodeBlock>}
</>
);
};
Loading