Markdown Format / Editor documentation + features

src-docs/src/routes.js

@@ -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: [

src-docs/src/views/markdown_editor/mardown_editor_example.js

@@ -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 (if configured to do
+          so). There are two modes: a 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 textarea and vice versa.
+        </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. The below example starts with an
+          incomplete tooltip tag, showing this error message by default. These
+          errors are meant to be ephemeral and part of the editing experience.
+          They should not be a substitute for{' '}
+          <Link to="/forms/form-validation">form validation</Link>.
+        </p>
+      ),
+      props: {
+        EuiMarkdownEditor,
+      },
+      demo: <MarkdownEditorErrors />,
+    },
   ],
 };

src-docs/src/views/markdown_editor/mardown_format_example.js

@@ -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 />,
+    },
+  ],
+};

src-docs/src/views/markdown_editor/markdown_editor.js

@@ -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}
       />

src-docs/src/views/markdown_editor/markdown_editor_errors.js

@@ -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>}
+    </>
+  );
+};