+
+
+ 
+
+
+ 
+
+
+ 
+
+
- 
- 
- 
-BearToCode/carta
+ {#if loading} + + {:else} +{result.match.text}
+ {/if} + + +
+
+
+
+```ts
+const ext: Plugin = {
+ // ...
+};
+
+const carta = new Carta({
+ extensions: [ext]
+});
+```
+
+
+
+Here are all the `Plugin` properties:
+
+### `transformers`
+
+Type: `UnifiedTransformer`
+
+Remark or Rehype transformers.
+
+#### `UnifiedTransformer.execution`
+
+Type: `'sync' | 'async'`
+
+If you specify async, this transformer won't be available for SSR.
+
+#### `UnifiedTransformer.type`
+
+Type: `'remark' | 'rehype'`
+
+This determines at which step the transformer will operate, whether on Remark, on a Markdown-based syntax tree, or Rehype, on a HTML-based one.
+
+#### `UnifiedTransformer.transform`
+
+Type: `({ processor, carta }) => void`
+
+The actual processor, can be async if the execution is specified as such.
+
+
+
+```ts
+{
+ execution: 'sync',
+ type: 'rehype',
+ transform({ processor }) {
+ processor
+ .use(rehypeSlug)
+ .use(rehypeAutolinkHeadings);
+ }
+}
+```
+
+
+
+### `shortcuts`
+
+Type: `KeyboardShortcut[]`
+
+Additional keyboards shortcut. For example:
+
+
+
+```ts
+const shortcut: KeyboardShortcut = {
+ id: 'bold',
+ combination: new Set(['control', 'b']),
+ action: (input) => input.toggleSelectionSurrounding('**')
+};
+```
+
+
+
+#### `KeyboardShortcut.id`
+
+Type: `string`
+
+Id of the shortcut.
+
+#### `KeyboardShortcut.combination`
+
+Type: `Set
+
+```ts
+const icon: Icon = {
+ id: 'heading',
+ action: (input) => input.toggleLinePrefix('###'),
+ component: HeadingIcon
+};
+```
+
+
+
+#### `Icon.id`
+
+Type: `string`
+
+Id of the icon.
+
+#### `Icon.action`
+
+Type: `(input: InputEnhancer) => void`
+
+Click callback.
+
+#### `Icon.component`
+
+Type: `ComponentType` (SvelteComponent)
+
+The Icon as a Svelte component.
+
+### `prefixes`
+
+Type: `Prefix[]`
+
+Text prefixes, default ones include the `- ` for bulleted lists, `1. ` for numbered lists, `- [ ]` for task lists.
+
+
+
+```ts
+const prefix: Prefix = {
+ id: 'bulletedList',
+ match: (line) => {
+ const prefix = line.slice(0, 2);
+ if (prefix === '- ') return prefix;
+ },
+ maker: () => '- '
+};
+```
+
+
+
+#### `Prefix.id`
+
+Type: `string`
+
+Id of the prefix.
+
+#### `Prefix.match`
+
+Type: `(line: string) => string | undefined`
+
+Function that returns the prefix, if it is present.
+
+#### `Prefix.maker`
+
+Type: `(previousMatch: string, previousLine: string) => string`
+
+Function that returns the prefix for the new line.
+
+Example:
+
+
+
+```ts
+const prefix: Prefix = {
+ id: 'numberedList',
+ match: (line) => line.match(/^\d+\./)?.at(0),
+ maker: (prev) => `${Number(prev.slice(0, -1)) + 1}. `
+};
+```
+
+
+
+### `listeners`
+
+Type: `Listener[]`
+
+Textarea event listeners. Has an additional `carta-render` and `carta-render-ssr` events keys.
+
+
+
+```ts
+const click: Listener = ['click', () => console.log('I was clicked!')];
+const render: Listener = [
+ 'carta-render',
+ (e) => {
+ const carta = e.detail.carta;
+ // ...
+ },
+ {
+ once: true
+ }
+];
+```
+
+
+
+### `components`
+
+Type: `ExtensionComponent[]`
+
+Additional components to be added to the editor or viewer.
+
+#### `ExtensionComponent
+
+```
+npm i carta-plugin-video
+```
+
+
+
+
+
+```
+npm i carta-plugin-imsize
+```
+
+
+
+
+
+```
+npm i carta-plugin-ins-del
+```
+
+
+
+
+
+```
+npm i carta-plugin-subscript
+```
+
+
diff --git a/docs/src/pages/editing-styles.svelte.md b/docs/src/pages/editing-styles.svelte.md
new file mode 100644
index 0000000..81736ed
--- /dev/null
+++ b/docs/src/pages/editing-styles.svelte.md
@@ -0,0 +1,111 @@
+---
+title: Editing Styles
+section: Overview
+---
+
+
+
+## Customizing editor styles
+
+While the core styles are embedded in the Svelte components, the others can be set in a custom stylesheet. Here is what the final rendered HTML looks like.
+
+
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+
+
+### Using multiple themes
+
+By using the `theme` property in `
+
+```css
+/* Editor dark mode */
+/* Only if you are using the default theme */
+html.dark .carta-theme__default {
+ --border-color: var(--border-color-dark);
+ --selection-color: var(--selection-color-dark);
+ --focus-outline: var(--focus-outline-dark);
+ --hover-color: var(--hover-color-dark);
+ --caret-color: var(--caret-color-dark);
+ --text-color: var(--text-color-dark);
+}
+
+/* Code dark mode */
+/* Only if you didn't specify a custom code theme */
+html.dark .shiki,
+html.dark .shiki span {
+ color: var(--shiki-dark) !important;
+}
+```
+
+
+
+## Changing Markdown input color theme
+
+Carta uses [Shiki](https://shiki.matsu.io/) for syntax highlighting. Two default themes are included in the core package, which are set as a [dual theme](https://shiki.matsu.io/guide/dual-themes) to support light and dark mode. If you plan to use a custom one with light/dark modes, make sure to use a dual theme as well.
+
+You can change theme in the options:
+
+
+
+```ts
+const carta = new Carta({
+ // ...
+ theme: 'github-dark'
+});
+```
+
+
+
+If you use a [custom theme](https://shiki.matsu.io/guide/load-theme)(or a custom language), you need to provide it inside the options, so that it gets loaded into the highlighter:
+
+
+
+```ts
+const carta = new Carta({
+ // ...
+ shikiOptions: {
+ langs: // ...
+ themes: // ...
+ }
+})
+```
+
+
+
+## Markdown stylesheets
+
+Markdown is converted into standard HTML, so you can edit the final styles by using standard CSS rules. If you do not wish to create one from the ground up, you can use some already complete stylesheets, like [github-markdown-css](https://github.com/sindresorhus/github-markdown-css) or [Tailwind Typography](https://tailwindcss.com/docs/typography-plugin).
diff --git a/docs/src/pages/examples.svelte.md b/docs/src/pages/examples.svelte.md
new file mode 100644
index 0000000..dcdd61e
--- /dev/null
+++ b/docs/src/pages/examples.svelte.md
@@ -0,0 +1,33 @@
+---
+title: Examples
+section: Overview
+---
+
+
+
+Here is a list of examples made using Carta and some of its plugins.
+
+## GitHub
+
+
+
+```
+npm i carta-md
+```
+
+
+
+Installing plugins:
+
+
+
+```
+npm i @cartamd/plugin-name
+```
+
+
+
+## Setup
+
+Setup a basic editor:
+
+
+
+```svelte
+
+
+
+
+Or, if you just want to render content:
+
+
+
+```svelte
+
+
+
+
+## Sanitization
+
+By default Carta does **not** sanitize user input, which can include malicious code that could lead to [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). For this reason it is _strongly recommended_ to install a package that handles that for you.
+
+Since Carta operates both on the server and the client, you'd need a sanitizer able to work in both environments, for example [isomorphic-dompurify](https://www.npmjs.com/package/isomorphic-dompurify) or [sanitize-html](https://www.npmjs.com/package/sanitize-html). Here is an example using the former, which requires minimum configuration.
+
+
+
+```svelte
+
+
+
diff --git a/docs/src/pages/introduction.svelte.md b/docs/src/pages/introduction.svelte.md
new file mode 100644
index 0000000..12e0af9
--- /dev/null
+++ b/docs/src/pages/introduction.svelte.md
@@ -0,0 +1,130 @@
+---
+title: Carta
+section: Overview
+---
+
+
+
+> Modern, lightweight, powerful Markdown Editor.
+
+Carta is a lightweight, fast and extensible Svelte Markdown editor and viewer, designed for flexibility. It works natively in SvelteKit, and supports Server Side Rendering.
+
+## Features
+
+- ๐ Markdown syntax highlighting ([Shiki](https://shiki.style/));
+- ๐ ๏ธ Toolbar (extensible);
+- โจ๏ธ Keyboard **shortcuts** (extensible);
+- ๐ฆ Supports **[+150 plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins)** thanks to remark.
+- ๐ Scroll sync;
+- โ
Accessibility friendly;
+- ๐ฅ๏ธ **SSR** compatible;
+
+## Official Plugins
+
+Carta comes with a set of official plugins for the most common use cases.
+
+
+
+```
+npm i @cartamd/plugin-anchor
+```
+
+
+
+## Setup
+
+### Styles
+
+Import the default theme, or create you own:
+
+
+
+```ts
+import '@cartamd/plugin-anchor/default.css';
+```
+
+
+
+### Extension
+
+
+
+```svelte
+
+
+
+
+## Options
+
+Here are the options you can pass to `anchor()`:
+
+```ts
+export interface AnchorExtensionOptions {
+ /**
+ * rehype-slug options.
+ */
+ slug?: SlugOptions;
+ /**
+ * rehype-autolink-headings options.
+ */
+ autolink?: AutolinkOptions;
+}
+```
diff --git a/docs/src/pages/plugins/attachment.svelte.md b/docs/src/pages/plugins/attachment.svelte.md
new file mode 100644
index 0000000..bbd0eca
--- /dev/null
+++ b/docs/src/pages/plugins/attachment.svelte.md
@@ -0,0 +1,91 @@
+---
+section: Plugins
+title: Attachment
+---
+
+
+
+This plugin adds support for attachments.
+
+## Installation
+
+```
+npm i @cartamd/plugin-attachment
+```
+
+## Setup
+
+### Styles
+
+Import the default theme, or create you own:
+
+
+
+```ts
+import '@cartamd/plugin-attachment/default.css';
+```
+
+
+
+### Extension
+
+
+
+```svelte
+
+
+
+
+## Options
+
+Here are the options you can pass to `attachment()`:
+
+```ts
+export interface AttachmentExtensionOptions {
+ /**
+ * Upload a file to the server. Return the url of the uploaded file.
+ * If an error occurs, return null. This function does **not** handle errors.
+ * @param file The file to upload
+ * @returns The uploaded file url, or null if it failed
+ */
+ upload: (file: File) => Promise
+
+```
+npm i @cartamd/plugin-code
+```
+
+
+
+## Setup
+
+### Styles
+
+Import the default styles:
+
+
+
+```ts
+import '@cartamd/plugin-code/default.css';
+```
+
+
+
+### Using the default highlighter
+
+Carta comes with a default highlighter that matches the one used to highlight markdown in the editor and is used by default (Shiki). If you want to use a theme different from the one used to highlight Markdown, you can specify it in the options.
+
+
+
+```ts
+const carta = new Carta({
+ // ...
+ extensions: [
+ code({
+ theme: 'ayu-light'
+ })
+ ]
+});
+```
+
+
+
+### Using a custom highlighter
+
+It is no longer possible to specify a custom highlighter in this plugin. However, there are many different [Remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) that provide syntax highlighting.
+
+### Extension
+
+
+
+```svelte
+
+
+
+
+## Options
+
+The options you can pass to `code()` extend the ones provided by [Shiki](https://shiki.matsu.io/guide/transformers).
diff --git a/docs/src/pages/plugins/emoji.svelte.md b/docs/src/pages/plugins/emoji.svelte.md
new file mode 100644
index 0000000..e7162bd
--- /dev/null
+++ b/docs/src/pages/plugins/emoji.svelte.md
@@ -0,0 +1,70 @@
+---
+section: Plugins
+title: Emoji
+---
+
+
+
+This plugin adds support for **Emojis**.
+
+## Installation
+
+
+
+```
+npm i @cartamd/plugin-emoji
+```
+
+
+
+## Setup
+
+### Styles
+
+Import the default theme, or create you own:
+
+
+
+```ts
+import '@cartamd/plugin-emoji/default.css';
+```
+
+
+
+### Extension
+
+
+
+```svelte
+
+
+
+
+## Options
+
+Here are the options you can pass to `emoji()`:
+
+```ts
+export interface EmojiExtensionOptions {
+ /**
+ * Custom in transition. See https://svelte.dev/docs#run-time-svelte-transition.
+ */
+ inTransition?: (node: Element) => TransitionConfig;
+ /**
+ * Custom out transition. See https://svelte.dev/docs#run-time-svelte-transition.
+ */
+ outTransition?: (node: Element) => TransitionConfig;
+}
+```
diff --git a/docs/src/pages/plugins/math.svelte.md b/docs/src/pages/plugins/math.svelte.md
new file mode 100644
index 0000000..7d4cc5c
--- /dev/null
+++ b/docs/src/pages/plugins/math.svelte.md
@@ -0,0 +1,160 @@
+---
+section: Plugins
+title: Math
+---
+
+
+
+This plugins adds support for [KaTeX](https://katex.org/) expressions.
+
+## Installation
+
+
+
+```
+npm i @cartamd/plugin-math
+```
+
+
+
+## Setup
+
+### Styles
+
+You need to get access to the katex **stylesheet**,
+to do so, you can either install katex using:
+
+
+
+```
+npm i katex
+```
+
+
+
+and then adding this import to your app:
+
+
+
+```ts
+import 'katex/dist/katex.css';
+```
+
+
+
+or by using a content delivery network:
+
+
+
+```html
+
+```
+
+
+
+### Extension
+
+
+
+```svelte
+
+
+
+
+## Usage
+
+Inline:
+
+
+
+```
+Pythagorean theorem: $a^2+b^2=c^2$
+```
+
+
+
+
+
+```
+$$
+ \\mathcal{L}\\{f\\}(s) = \\int_0^{\\infty} {f(t)e^{-st}dt}
+$$
+```
+
+
+
+
+
+```
+npm i @cartamd/plugin-slash
+```
+
+
+
+## Setup
+
+### Styles
+
+Import the default theme, or create you own:
+
+
+
+```ts
+import '@cartamd/plugin-slash/default.css';
+```
+
+
+
+### Extension
+
+
+
+```svelte
+
+
+
+
+## Options
+
+Here are the options you can pass to `slash()`:
+
+```ts
+export interface SlashExtensionOptions {
+ /**
+ * List of default snippets to disable.
+ */
+ disableDefaultSnippets?: DefaultSnippetId[] | true;
+ /**
+ * Additional snippets.
+ */
+ snippets?: SlashSnippet[];
+ /**
+ * Custom in transition. See https://svelte.dev/docs#run-time-svelte-transition.
+ */
+ inTransition?: (node: Element) => TransitionConfig;
+ /**
+ * Custom out transition. See https://svelte.dev/docs#run-time-svelte-transition.
+ */
+ outTransition?: (node: Element) => TransitionConfig;
+}
+```
diff --git a/docs/src/pages/plugins/tikz.svelte.md b/docs/src/pages/plugins/tikz.svelte.md
new file mode 100644
index 0000000..c878f8a
--- /dev/null
+++ b/docs/src/pages/plugins/tikz.svelte.md
@@ -0,0 +1,71 @@
+---
+section: Plugins
+title: TikZ
+---
+
+
+
+This plugin adds support for **PGF/TikZ** illustrations thanks to [TikZJax](https://tikzjax.com/). It uses the code generated for the [Obsidian-TikZ plugin](https://github.com/artisticat1/obsidian-tikzjax).
+
+
+
+```
+npm i @cartamd/plugin-tikz
+```
+
+
+
+## Important Notes
+
+1. This plugin requires the import of a **heavy** library (~7Mb), which is dynamically imported at runtime;
+2. Generated images are **not SSR compatible**, as they are rendered in the browser;
+3. You need to update your sanitizer to allow the specific tag: `
+
+```svelte
+
+
+
+
+## Options
+
+Here are the options you can pass to `tikz()`:
+
+```ts
+interface TikzExtensionOptions {
+ /**
+ * Enables Tikzjax console output.
+ */
+ debug?: boolean;
+ /**
+ * Class for generated svg div container.
+ */
+ class?: string;
+ /**
+ * Whether to center the generated expression.
+ * @default true
+ */
+ center?: boolean;
+ /**
+ * Post processing function for html.
+ * This also runs on stored html.
+ */
+ postProcessing?: (html: string) => string;
+}
+```
diff --git a/docs/src/pages/using-components.svelte.md b/docs/src/pages/using-components.svelte.md
new file mode 100644
index 0000000..f301c51
--- /dev/null
+++ b/docs/src/pages/using-components.svelte.md
@@ -0,0 +1,217 @@
+---
+title: Using Svelte Components
+section: Overview
+---
+
+
+
+Svelte components can be embedded into the rendered HTML to make certain elements interactive. However, they require a bit more work, as Remark is configured to only render static HTML. To get around this, the idea is to do the following:
+
+1. Create a Unified plugin to isolate the targeted element;
+2. Replace all the elements with the component, after every render.
+
+## Example
+
+Let's say we want to replace all hashtags, such as `#something`, with a custom component. Here is as example of how that could be achieved.
+
+### Parsing the hashtags
+
+First things first: we need to tell the parser that we want to parse hashtags as custom elements. To do this, it's useful to first install the following packages:
+
+
+
+```shell
+npm i unist-util-visit
+# Types
+npm i -D unified hast
+```
+
+
+
+Let's create a Unified plugin. The basic structure of a plugin is the following:
+
+
+
+```ts
+import type { Plugin as UnifiedPlugin } from 'unified'
+import { SKIP, visit } from 'unist-util-visit'
+
+const unifiedPlugin: UnifiedPlugin<[], hast.Root> = () => {
+ return function (tree) {
+ // Visit every node in the syntax tree
+ visit(tree, (node, index, parent) => {
+ // Do something with the node
+ }
+ }
+}
+```
+
+
+
+We now want to parse text nodes, so that words such as `#pizza` and `#123` are separated from the rest. This is a possible implementation:
+
+
+
+```ts
+const unifiedPlugin: UnifiedPlugin<[], hast.Root> = () => {
+ return function (tree) {
+ visit(tree, (node, index, parent) => {
+ // Skip code blocks and their children
+ if (node.type === 'element' && node.tagName === 'pre') return [SKIP];
+ // Skip non-text nodes
+ if (node.type !== 'text') return;
+ const text = node as hast.Text;
+
+ // Parse the text node and replace hashtags with spans
+ const regex = /#(\w+)/g;
+ const children: (hast.Element | hast.Text)[] = [];
+ let lastIndex = 0;
+ let match;
+ while ((match = regex.exec(text.value))) {
+ const before = text.value.slice(lastIndex, match.index);
+ if (before) {
+ children.push({ type: 'text', value: before });
+ }
+ children.push({
+ type: 'element',
+ tagName: 'span',
+ properties: { type: 'hashtag', value: match[1] },
+ children: [{ type: 'text', value: match[0] }]
+ });
+ lastIndex = regex.lastIndex;
+ }
+ if (lastIndex < text.value.length) {
+ children.push({ type: 'text', value: text.value.slice(lastIndex) });
+ }
+
+ // Replace the text node with all the children
+ parent!.children.splice(index!, 1, ...children);
+
+ // Skip the children
+ return [SKIP, index! + children.length];
+ });
+ };
+};
+```
+
+
+
+If you want a more in-depth guide on writing Unified plugins, you can check out the official [documentation](https://unifiedjs.com/learn/guide/create-a-plugin/).
+
+Notice that hashtags are now replaced with the following:
+
+```html
+ #pizza
+```
+
+### Configuring the transformer
+
+Unified plugins need to be wrapped inside a `UnifiedTransformer` type, to be able to be used in Carta.
+
+
+
+```ts
+import type { UnifiedTransformer } from 'carta-md';
+
+const hashtagTransformer: UnifiedTransformer<'sync'> = {
+ execution: 'sync', // Sync, since the plugin is synchronous
+ type: 'rehype', // Rehype, since it operates on HTML
+ transform({ processor }) {
+ processor.use(unifiedPlugin);
+ }
+};
+```
+
+
+
+### Mounting the components
+
+We now want to replace the generated hashtag placeholders with the following element:
+
+
+
+```svelte
+
+
+
+
+```
+
+
+
+To do that, we create a listener that:
+
+1. Finds all the previous placeholders;
+2. Mounts the component next to them;
+3. Removes the placeholders.
+
+
+
+```ts
+import type { Listener } from 'carta-md';
+import Hashtag from './Hashtag.svelte';
+
+const convertHashtags: Listener<'carta-render'> = [
+ 'carta-render',
+ function onRender({ detail: { carta } }) {
+ const rendererContainer = carta.renderer?.container;
+ if (!rendererContainer) return;
+
+ // Find all hashtag spans and replace them with Svelte components
+ const hashtagSpans = rendererContainer.querySelectorAll('span[type="hashtag"]');
+ for (const span of hashtagSpans) {
+ const hashtag = span.getAttribute('value') ?? '';
+
+ new Hashtag({
+ target: span.parentElement!,
+ anchor: span,
+ props: { value: hashtag }
+ });
+
+ span.remove();
+ }
+ }
+];
+```
+
+
+
+### Using the plugin
+
+Let's now create a Plugin with the transformer and the listener:
+
+
+
+```ts
+import type { Plugin } from 'carta-md';
+
+export const hashtag = (): Plugin => ({
+ transformers: [hashtagTransformer],
+ listeners: [convertHashtags]
+});
+```
+
+
+
+We can now use the plugin with the following:
+
+```ts
+import { Carta } from 'carta-md';
+
+const carta = new Carta({
+ // ...
+ extensions: [hashtag()]
+});
+```
+
+You can find the example source code [here](https://github.com/BearToCode/svelte-in-carta-example).
diff --git a/docs/src/routes/+layout.svelte b/docs/src/routes/+layout.svelte
new file mode 100644
index 0000000..723f83f
--- /dev/null
+++ b/docs/src/routes/+layout.svelte
@@ -0,0 +1,29 @@
+
+
+
-
-
-
-