diff --git a/.gitignore b/.gitignore index bad74bfb..8225b310 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ node_modules/ .DS_Store **/dist **.tgz -docs temp etc uploads diff --git a/docs/admonitions.md b/docs/admonitions.md new file mode 100644 index 00000000..efe93dcf --- /dev/null +++ b/docs/admonitions.md @@ -0,0 +1,55 @@ +--- +title: Admonitions +slug: Admonitions +position: 0.815 +--- + +# Admonitions + +Admonitions (also known as callouts or tips) are a common way to highlight some text in a markdown document. [Docusaurus uses them extensively](https://docusaurus.io/docs/markdown-features/admonitions) in its documentation, and provides a pre-made styling (icons, colors, etc). + +The admonitions are, in fact, just [conventional container directives](./directives). The MDXEditor package ships a pre-made directive `AdmonitionDirectiveDescriptor` that enables the usage of admonitions in your markdown document. + +```tsx +const admonitionMarkdown = ` + +:::note +foo +::: + +:::tip +Some **content** with _Markdown_ syntax. Check [this component](https://virtuoso.dev/). +::: + +:::info +Some **content** with _Markdown_ syntax. +::: + +:::caution +Some **content** with _Markdown_ syntax. +::: + +:::danger +Some **content** with _Markdown_ syntax. +::: +` + + +export const Admonitions: React.FC = () => { + return ( + + ) +} +``` diff --git a/docs/basic-formatting.md b/docs/basic-formatting.md new file mode 100644 index 00000000..3bf9110c --- /dev/null +++ b/docs/basic-formatting.md @@ -0,0 +1,79 @@ +--- +title: Basic Formatting +slug: basic-formatting +position: 0.1 +--- + +# Basic Formatting + +In its bare form, MDXEditor supports only the most basic formatting - **bold**, *italic*, underline and `inline code`. It's enough to write a simple text, but not much more. There are several plugins that allow the users to create a document structure and apply semantic formatting. + +## Headings + +The Headings plugin enables the usage of markdown headings which translate to `H1` - `H6` in HTML. + +```tsx + +import { MDXEditor } from '@mdxeditor/editor/MDXEditor' +import { headingsPlugin } from '@mdxeditor/editor/plugins/headings' + +//... + +``` + +## Quotes + +The Quote plugin enables the usage of quotes which translate to `blockquote` in HTML. + +```tsx + +import { MDXEditor } from '@mdxeditor/editor/MDXEditor' +import { quotePlugin } from '@mdxeditor/editor/plugins/quote' + +const markdown = "> This is a quote" + +//... + +``` + +## Lists + +The Lists plugin enables the usage of ordered and unordered lists, including multiple levels of nesting. + +```tsx + +import { MDXEditor } from '@mdxeditor/editor/MDXEditor' +import { listsPlugin } from '@mdxeditor/editor/plugins/lists' + +const markdown = ` + * Item 1 + * Item 2 + * Item 3 + * nested item + + 1. Item 1 + 2. Item 2 +` + +//... + +``` + +## Thematic Break + +The Thematic Break plugin enables the usage of thematic breaks which translate to `hr` in HTML. + +```tsx +import { MDXEditor } from '@mdxeditor/editor/MDXEditor' +import { thematicBreakPlugin } from '@mdxeditor/editor/plugins/thematic-break' + +const markdown = ` +Hello + +--- + +World +` + +//... + diff --git a/docs/code-blocks.md b/docs/code-blocks.md new file mode 100644 index 00000000..fbad184c --- /dev/null +++ b/docs/code-blocks.md @@ -0,0 +1,139 @@ +--- +title: Code blocks +slug: code-blocks +position: 0.6 +--- + +# Code blocks + +The code block plugin enables support for fenced code blocks, but does not include any code editing UI. The `codeMirrorPlugin` and the `sandpackPlugin` build on top of it to provide a code editing experience. The next example enables both plugins along with their respective toolbar components. + +```tsx +const defaultSnippetContent = ` +export default function App() { + return ( +
+

Hello CodeSandbox

+

Start editing to see some magic happen!

+
+ ); +} +`.trim() + +const simpleSandpackConfig: SandpackConfig = { + defaultPreset: 'react', + presets: [ + { + label: 'React', + name: 'react', + meta: 'live react', + sandpackTemplate: 'react', + sandpackTheme: 'light', + snippetFileName: '/App.js', + snippetLanguage: 'jsx', + initialSnippetContent: defaultSnippetContent + }, + ] +} + +function App() { + return ( + ( + editor?.editorType === 'codeblock', contents: () => }, + { when: (editor) => editor?.editorType === 'sandpack', contents: () => }, + { fallback: () => ( <> + + + ) } + ]} + />) + }) + ] + } + /> + ) +} +``` + +````md +Blocks of code + +JavaScript: + +```js +export default function App() { + return

Hello world from a markdown

+} +``` + +CSS: + +```css +body { + color: red; +} +``` + +React Sandpack: + +```tsx live react +export default function App() { + return

Hello world from a markdown

+} +``` +```` + +## Configuring the CodeMirror editor + +The code mirror editor plugin enables editing of fenced code blocks with basic code editing features like syntax highlighting, indentation and bracket matching. A set of toolbar component utilities support the display of a language selector when the block is in focus, while hiding the rich text editor controls. The plugin accepts supported languages as a parameter option. + +## Configuring the Sandpack editor + +Compared to the code mirror editor, the Sandpack one is a bit more complex, as Sandpack needs to know the context of the code block in order to execute it correctly. Before diving in, it's good to [understand Sandpack configuration](https://sandpack.codesandbox.io/) itself. MDXEditor supports multiple Sandpack configurations, based on the meta data of the code block. To configure the supported presets, pass a `sandpackConfig` option in the plugin initialization. For more details, refer to the [SandpackConfig interface](../api/editor.sandpackconfig) and the [SandpackPreset interface](../api/editor.sandpackpreset). + +## Build a custom code block editor + +You can implement your own stack of custom code editors by passing a code block editor descriptor to the `codeBlockPlugin`. The next example uses a plain text textarea to edit the code block content. More details about each of the constructs in the example can be found in the API reference. + +```tsx +const PlainTextCodeEditorDescriptor: CodeBlockEditorDescriptor = { + // always use the editor, no matter the language or the meta of the code block + match: (language, meta) => true, + // You can have multiple editors with different priorities, so that there's a "catch-all" editor (with the lowest priority) + priority: 0, + // The Editor is a React component + Editor: (props) => { + const cb = useCodeBlockEditorContext() + // stops the proppagation so that the parent lexical editor does not handle certain events. + return ( +
e.nativeEvent.stopImmediatePropagation()}> +