# Markdown

Die Markdown Component rendert Texteingaben im Markdown-Format.

## Overview

# Playground

Um eine Texteingabe als Markdown zu rendern, schließe sie mit dem
`<Markdown />`-Tag ein.

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

---

# Color

Zusätzlich zur Standard-Color kann Markdown auch in den Colors **Light** und
**Dark** dargestellt werden. Beide Colors sind Alternativen zur Standard-Color,
falls diese nicht auf farbigen oder dekorativen Hintergründen funktioniert.

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown color="light">
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown color="dark">
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

**Light:** Verwende die Light-Color bei dunklen Hintergründen mit einem HSL
Lightness-Wert von weniger als 50.

**Dark:** Verwende die Dark-Color bei hellen, farbigen Hintergründen mit einem
HSL Lightness-Wert von größer als 50.

---

# Unterstützte Syntax

## Headings

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  {
    "# Heading Level 1 \n## Heading Level 2 \n### Heading Level 3 \n#### Heading Level 4 \n##### Heading Level 5 \n###### Heading Level 6"
  }
</Markdown>
```

## Bold und Italic

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  Lorem ipsum dolor sit amet **consectetur adipisicing**
  elit. Cumque eius *quam quas vel voluptas* ullam aliquid
  ***fugit***.
</Markdown>
```

## Unordered Lists

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  {
    "- Unordered list item 1 \n - Unordered list item 2  \n - Unordered list item 3"
  }
</Markdown>
```

## Ordered Lists

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  {
    "1. Ordered list item 1 \n 2. Ordered list item 2  \n 3. Ordered list item 3"
  }
</Markdown>
```

## Quote

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>{"> This is a quote"}</Markdown>
```

## Link

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>[mittwald.de](https://mittwald.de).</Markdown>
```

## InlineCode

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>{"`127.0.0.1`"}</Markdown>
```

## CodeBlock

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  {"```json\n" +
    "{\n" +
    '    "projectId": "b3a96db5-ba8f-40dd-9100-bab43ac1f698",\n' +
    '    "name": "My Project"\n' +
    "}\n" +
    "```\n"}
</Markdown>
```

## Table

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown>
  {"| Column 1       | Column 2      |\n" +
    "|---------------|---------------|\n" +
    "| Row 1 Cell 1  | Row 1 Cell 2  |\n" +
    "| Row 2 Cell 1  | Row 2 Cell 2  |\n"}
</Markdown>
```

---

# Offset

Das Property `headingOffset` verschiebt alle Überschriften um den angegebenen
Offset.

```tsx
import { Markdown } from "@mittwald/flow-react-components";

<Markdown headingOffset={1}>
  {
    "# Heading Level 1 -> 2 \n## Heading Level 2 -> 3 \n### Heading Level 3 -> 4 \n#### Heading Level 4 -> 5 \n##### Heading Level 5 -> 6 \n###### Heading Level 6 -> 6"
  }
</Markdown>
```


## Develop

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `"default" \| "dark" \| "light" \| "dark-static" \| "light-static"` | `"default"` | The color schema of the markdown component. |
| `headingOffset` | `number` | `0` | Shifts all heading levels by the given offset. |
| `components` | `Components` | - | Allows overriding markdown element renderers from outside. |
| `ref` | `Ref<HTMLDivElement>` | - | - |
| `className` | `string` | - | The elements class name. |
| `children` | `ReactNode` | - | Markdown. |
| `allowElement` | `AllowElement` | - | Filter elements (optional); `allowedElements` / `disallowedElements` is used first. |
| `allowedElements` | `readonly string[]` | - | Tag names to allow (default: all tag names); cannot combine w/ `disallowedElements`. |
| `disallowedElements` | `readonly string[]` | - | Tag names to disallow (default: `[]`); cannot combine w/ `allowedElements`. |
| `rehypePlugins` | `PluggableList` | - | List of rehype plugins to use. |
| `remarkPlugins` | `PluggableList` | - | List of remark plugins to use. |
| `remarkRehypeOptions` | `Readonly<Options>` | - | Options to pass through to `remark-rehype`. |
| `skipHtml` | `boolean` | - | Ignore HTML in markdown completely (default: `false`). |
| `unwrapDisallowed` | `boolean` | - | Extract (unwrap) what’s in disallowed elements (default: `false`); normally when say `strong` is not allowed, it and it’s children are dropped, with `unwrapDisallowed` the element itself is replaced by its children. |
| `urlTransform` | `UrlTransform` | - | Change URLs (default: `defaultUrlTransform`) |


## Guidelines

# Grundlagen

Markdown ist besonders nützlich in Situationen, in denen Texteingaben von Usern
geliefert werden. Die Ausgabe wird als HTML gerendert, jedoch ohne explizite
Kontrolle über semantische Elemente wie z. B. `<p>` oder `<h1>`. Für mehr
Kontrolle über das Layout sollte [Text](/04-components/content/text/overview)
verwendet werden.

## Best practices

Achte bei der Verwendung von Markdown darauf, dass sie hauptsächlich für
dynamische oder nutzergenerierte Texteingaben (z. B. im
[Chat](/04-components/chat/chat/overview)) genutzt wird.

## Verwendung

Verwende Markdown, um Texte im Markdown-Format korrekt darzustellen. Dieses
Format wird z. B. häufig von Usern in Kommentarfunktionen oder Chats genutzt.