docs: document the BBCode, Embed, Emoji and Markdown extensions

docs/extensions/bbcode.md

@@ -0,0 +1,43 @@
+---
+image: img/extensions/bbcode-share.png
+---
+
+# BBCode
+
+![BBCode: format posts with BBCode. Bundled with Flarum 2.0.](/img/docs/extensions/bbcode.png)
+
+The BBCode extension (`flarum/bbcode`) lets members format their posts with [BBCode](https://en.wikipedia.org/wiki/BBCode), the square-bracket tags used by many older forums. It is a [bundled extension](../extensions.md), and it is enabled by default.
+
+It is most useful for communities used to BBCode, and for content imported from forum software that stored posts as BBCode. It has no settings and no permissions: everyone who can post can use it. It adds no toolbar buttons; tags are typed by hand.
+
+## Supported tags
+
+| Tag | Example | Result |
+| --- | --- | --- |
+| `[b]` | `[b]bold[/b]` | **Bold** text |
+| `[i]` | `[i]italic[/i]` | _Italic_ text |
+| `[u]` | `[u]underline[/u]` | Underlined text |
+| `[s]`, `[del]` | `[s]struck[/s]` | Struck-through text |
+| `[color]` | `[color=red]red[/color]` | Colored text. Takes a color name or a hex code such as `#ff0000`. |
+| `[size]` | `[size=20]big[/size]` | Text at that size, in pixels. |
+| `[center]` | `[center]centered[/center]` | Centered text |
+| `[url]` | `[url=https://example.com]a link[/url]` or `[url]https://example.com[/url]` | A link |
+| `[email]` | `[email]name@example.com[/email]` | A link that opens the reader's email client |
+| `[img]` | `[img]https://example.com/image.png[/img]` | An image |
+| `[quote]` | `[quote=Name]quoted text[/quote]` | A quote. With a name, it is headed "Name wrote". |
+| `[code]` | `[code]some code[/code]` | A code block, with syntax highlighting |
+| `[list]`, `[*]` | `[list][*]one[*]two[/list]` | A bulleted list. Use `[list=1]` for a numbered list. |
+
+Tags can be nested, as in `[b][i]bold italic[/i][/b]`. A tag that is not on this list is shown as typed.
+
+The highlighting script for `[code]` blocks is loaded from the jsDelivr CDN the first time a post with a code block is shown.
+
+## Disabling the extension
+
+Posts keep their text if you disable BBCode, but its formatting stops showing. Formatting that [Markdown](markdown.md) can also produce, such as bold, quotes and lists, still renders while Markdown is enabled. Enable BBCode again and existing posts are formatted as before.
+
+## Working with other extensions
+
+| Extension | What it adds to BBCode |
+| --- | --- |
+| [Markdown](markdown.md) | Both can be enabled together, and a post can mix the two. |

docs/extensions/embed.md

@@ -0,0 +1,63 @@
+---
+image: img/extensions/embed-share.png
+---
+
+# Embed
+
+![Embed: embed Flarum discussions as comments on your blog. Bundled with Flarum 2.0.](/img/docs/extensions/embed.png)
+
+The Embed extension (`flarum/embed`) lets you show a Flarum discussion inside another website, such as under a blog post, as its comment section. Readers see the discussion's posts and can reply without leaving the page. It is a [bundled extension](../extensions.md), and it is disabled by default.
+
+It has no settings and no permissions. Anyone who can see a discussion on the forum can see it embedded, and replying follows the forum's usual permissions.
+
+## Installation
+
+The extension ships with Flarum but is not enabled by default. Enable it from the **Extensions** page of the admin panel.
+
+If it is not present in your install, require it like any other package:
+
+```bash
+composer require flarum/embed
+php flarum cache:clear
+```
+
+## Embedding a discussion
+
+Each discussion has an embed address: its usual address with `/embed/` in place of `/d/`. For a discussion at `https://forum.example.com/d/123-welcome`, that is `https://forum.example.com/embed/123`. The slug after the number is optional, and `/embed/123/45` opens the discussion at post number 45.
+
+On the page where the discussion should appear, add an iframe pointing at that address, and the [iframe-resizer](https://github.com/davidjbradshaw/iframe-resizer) script, which keeps the iframe as tall as the discussion:
+
+```html
+<iframe id="flarum-embed" src="https://forum.example.com/embed/123" style="width: 100%; border: 0" scrolling="no"></iframe>
+
+<script src="https://cdn.jsdelivr.net/npm/iframe-resizer@4/js/iframeResizer.min.js"></script>
+<script>
+  iFrameResize({ checkOrigin: false }, '#flarum-embed');
+</script>
+```
+
+Use version 4 of iframe-resizer, which is the version the extension uses inside the iframe. Without the script, the iframe keeps whatever height you give it, and readers have to scroll inside it.
+
+To embed several discussions on one page, give each iframe its own `id`, or a shared class, and pass that selector to `iFrameResize`.
+
+## What readers see
+
+The embedded discussion shows its posts and the reply box, without the forum's header and navigation. Next to the posts are the **Reply** button and a link with the number of comments, which opens the discussion on the forum.
+
+Links inside the embed, such as a post's permalink or a member's name, open the forum in a new tab.
+
+## Logging in and replying
+
+Readers log in from inside the embed to reply. This works when the embedding site and the forum are on the same site, such as `blog.example.com` and `forum.example.com`.
+
+When they are on different sites, such as `myblog.com` and `forum.example.com`, browsers do not send the forum's login cookie to the embed. Readers are logged out inside it and cannot log in there, though they can still read the discussion and use the comments link to reply on the forum. To let them log in inside the embed, set the cookie's `samesite` option to `none` in the [configuration file](../config.md):
+
+```php
+'cookie' => [
+    'samesite' => 'none',
+],
+```
+
+This only works when the forum uses HTTPS. Browsers that block third-party cookies keep readers logged out in the embed regardless.
+
+Before Flarum 2.0.1, a browser that also blocks the forum's storage in the embed showed only a basic, read-only version of the discussion, with a message that the full version could not be loaded.

docs/extensions/emoji.md

@@ -0,0 +1,47 @@
+---
+image: img/extensions/emoji-share.png
+---
+
+# Emoji
+
+![Emoji: turn text and unicode emoji into Twemoji. Bundled with Flarum 2.0.](/img/docs/extensions/emoji.png)
+
+The Emoji extension (`flarum/emoji`) shows emoji in posts as [Twemoji](https://github.com/jdecked/twemoji) images, so they look the same on every device. It also turns text emoticons such as `:)` into emoji, and adds an emoji picker to the composer. It is a [bundled extension](../extensions.md), and it is enabled by default.
+
+It has no permissions: everyone who can post can use it.
+
+## Adding emoji to a post
+
+Type `:` followed by the start of an emoji's name, such as `:smi`, and pick one from the list that appears. The **Insert emoji** button in the composer toolbar starts the same list. Members can also paste or type emoji directly from their keyboard.
+
+The picked emoji is inserted into the post as a real emoji character. Typing a full name such as `:rocket:` without picking from the list leaves it as text.
+
+## Emoticons
+
+These text emoticons are shown as emoji:
+
+| Type | Get |
+| --- | --- |
+| `:)` | 🙂 |
+| `:D` | 😃 |
+| `:P` | 😛 |
+| `:(` | 🙁 |
+| `:\|` | 😐 |
+| `;)` | 😉 |
+| `:'(` | 😢 |
+| `:O` | 😮 |
+| `>:(` | 😡 |
+
+## How emoji are displayed
+
+Posts store emoji as ordinary characters. When a post is shown, each emoji is swapped for a Twemoji image, loaded from a CDN. The images are loaded lazily, as they scroll into view.
+
+If the extension is disabled, emoji characters stay in posts, and readers see them in their device's own emoji style. Emoticons go back to being shown as typed, such as `:)`. Enable the extension again and they are shown as emoji.
+
+## Settings
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| **CDN mirror address** | `https://cdn.jsdelivr.net/gh/jdecked/twemoji@[version]/assets/` | Where the Twemoji images are loaded from. `[version]` is replaced with the Twemoji version the extension uses, shown under the setting. |
+
+Change the address to use a mirror, for example if jsDelivr is slow or blocked for your members, or to host the images yourself. The address must end with `/`, and serve the `72x72/` folder of PNG images from the [Twemoji assets](https://github.com/jdecked/twemoji/tree/main/assets).

docs/extensions/markdown.md

@@ -0,0 +1,58 @@
+---
+image: img/extensions/markdown-share.png
+---
+
+# Markdown
+
+![Markdown: format posts with Markdown. Bundled with Flarum 2.0.](/img/docs/extensions/markdown.png)
+
+The Markdown extension (`flarum/markdown`) lets members format their posts with [Markdown](https://commonmark.org/help/), and adds a formatting toolbar to the composer. It is a [bundled extension](../extensions.md), and it is enabled by default.
+
+It has no settings and no permissions: everyone who can post can use it.
+
+## Formatting posts
+
+Markdown is written as plain text, so a post reads naturally even before it is formatted. The composer's preview shows the result as you type.
+
+| To get | Write |
+| --- | --- |
+| **Bold** | `**bold**` |
+| _Italic_ | `_italic_` or `*italic*` |
+| ~~Strikethrough~~ | `~~strikethrough~~` |
+| `Inline code` | `` `inline code` `` |
+| Superscript | `^superscript` |
+| Subscript | `~subscript` |
+| A heading | `# Heading` at the start of a line (one to six `#`) |
+| A link | `[text](https://example.com)` |
+| An image | `![description](https://example.com/image.png)` |
+| A quote | `> quoted text` at the start of a line |
+| A bulleted list | `- item` (or `*` or `+`) on each line |
+| A numbered list | `1. item` on each line |
+| A horizontal line | `---` on a line of its own |
+| A code block | The code between two lines of three backticks: ` ``` ` |
+| A spoiler | `>!hidden text!<` or `\|\|hidden text\|\|` within a line, or `>! ` at the start of a line for a whole paragraph |
+
+A code block can name its language on the opening line, as in ` ```php `, to get syntax highlighting. The highlighting script is loaded from the jsDelivr CDN the first time a post with a code block is shown.
+
+Spoilers are hidden until a reader clicks them.
+
+Tables are not supported. Pipe-table syntax such as `| a | b |` is shown as plain text.
+
+## The formatting toolbar
+
+The composer gets a toolbar with buttons for headings, bold, italic, strikethrough, quotes, spoilers, code, links, images, bulleted lists and numbered lists. A button wraps the selected text in the matching Markdown, or inserts it at the cursor.
+
+There are two keyboard shortcuts: **Ctrl+B** for bold and **Ctrl+I** for italic (**⌘B** and **⌘I** on a Mac).
+
+When you press **Enter** at the end of a list item, the next line starts a new item, numbered one higher in a numbered list. Pressing **Enter** on an empty item ends the list.
+
+## Disabling the extension
+
+Posts keep their text if you disable Markdown, but its formatting stops showing: headings, emphasis, links and the rest become plain text, and the Markdown characters themselves are not shown. Formatting that [BBCode](bbcode.md) can also produce, such as quotes and lists, still renders while BBCode is enabled. Enable Markdown again and existing posts are formatted as before.
+
+## Working with other extensions
+
+| Extension | What it adds to Markdown |
+| --- | --- |
+| [BBCode](bbcode.md) | Both can be enabled together, and a post can mix the two. |
+| [Emoji](emoji.md) | Adds its emoji button to the same composer toolbar. |

sidebars.js

@@ -66,8 +66,12 @@ module.exports = {
       items: [
         'extensions/akismet',
         'extensions/audit',
+        'extensions/bbcode',
         'extensions/deck',
+        'extensions/embed',
+        'extensions/emoji',
         'extensions/gdpr',
+        'extensions/markdown',
         'extensions/messages',
         'extensions/nicknames',
         'extensions/realtime',