DOCSEARCHbyAlgolia
Submit Docs

Carta Documentation

repository·master·Indexed 20 days ago

https://github.com/beartocode/carta

A lightweight, fast, and extensible Markdown editor and viewer built for Svelte, leveraging the unified/remark/rehype ecosystem. Includes a suite of plugins for extended functionality: @cartamd/plugin-anchor for permalinks, @cartamd/plugin-attachment for file uploads, @cartamd/plugin-code for Shiki-powered syntax highlighting, @cartamd/plugin-component for mapping HTML to Svelte components, @cartamd/plugin-emoji for emoji support, @cartamd/plugin-math for KaTeX expressions, @cartamd/plugin-slash for slash commands, and @cartamd/plugin-tikz for TikzJax illustrations.

Tokens
17.3K
Snippets
74
Records
88
Agent score
67%

What's inside Carta

  4. Initialize components during pre-rendering

    master

    When using the <PreRendered> component for server-side rendering, mapped components are not mounted automatically. You must manually call initializeComponents inside an onMount lifecycle hook, passing the array of mapped components and the container element.

    <script>
	import { initializeComponents } from '@cartamd/plugin-component/svelte';
	import { onMount } from 'svelte';

	export let data;
	let container;

	// This must match the mappings used in the editor
	const mapped = [
		/* ... your svelte() mappings ... */
	];

	onMount(() => {
		initializeComponents(mapped, container);
	});
</script>

<div bind:this={container}>
	<PreRendered html={data.html} />
</div>

  6. Markdown syntax supported by Carta

    master

    Carta supports standard Markdown syntax for content authoring. Key features include:

    • Text Formatting: _italic_, **bold**, and `monospace`.
    • Line Breaks: Use two spaces at the end of a line for a manual line break, or separate paragraphs with a blank line.
    • Lists: Supports both bulleted lists (- item) and numbered lists (1. item).
    • Emphasis: Supports strikethrough using ~~text~~.
    • Blockquotes: Use > at the start of lines for blockquoting.
    • Links and Images: Standard Markdown syntax for links [text](url) and images ![alt](url).
    • Tables: Supports GitHub-flavored Markdown tables.
    • Horizontal Rules: Use --- to create a horizontal rule.
    • Code Blocks: Supports fenced code blocks with language identifiers (e.g., ```js).
    **bold text**

- Bullet list item

1. Numbered list item

[Link text](http://example.com)

| Header | Header |
| ------ | ------ |
| Cell   | Cell   |

  8. Map HTML elements to Svelte components

    master

    To use custom renderers for specific nodes (like images), you must map the HTML tag name to a Svelte component. Use the svelte helper from @cartamd/plugin-component/svelte to create these mappings and pass them to the component extension in your Carta configuration.

    For more complex selection logic, use svelteCustom which allows you to provide a predicate function to determine if a node should be replaced by the component.

    import { Carta } from 'carta-md';
import { component } from '@cartamd/plugin-component';
import { svelte, initializeComponents, svelteCustom } from '@cartamd/plugin-component/svelte';
import Image from './Image.svelte';
import MyComponent from './MyComponent.svelte';

// Standard mapping: maps <img> tags to the Image component
const mapped = [svelte('img', Image)];

// Custom mapping: uses a predicate to decide when to use MyComponent
const customMapped = [
	svelteCustom(
		'my-component-id',
		(node) => {
			// Logic to determine if this node should be replaced
			return node.id === 'special';
		},
		MyComponent
	)
];

const carta = new Carta({
	extensions: [component(mapped, initializeComponents)]
});

  9. Configure the Carta Slash Plugin

    master

    To use the Slash plugin, import the slash function from @cartamd/plugin-slash and include it in the extensions array of your Carta instance configuration. You should also import the default CSS to ensure the slash command UI is styled correctly.

    <script lang="ts">
	import { Carta, MarkdownEditor } from 'carta-md';
	import { slash } from '@cartamd/plugin-slash';
	import '@cartamd/plugin-slash/default.css';

	const carta = new Carta({
		extextensions: [slash()]
	});
</script>

<MarkdownEditor {carta} />

  10. Basic configuration of Carta in Svelte

    master

    To set up a basic Markdown editor, import Carta and MarkdownEditor from carta-md. You must also import the default CSS for styling.

    Important Security Note: Carta does not handle sanitization automatically. You must provide a sanitizer in the Carta constructor options (e.g., using isomorphic-dompurify) to prevent XSS attacks.

    Styling Requirement: You must set a monospace font for the .carta-font-code class in your CSS to ensure the editor functions correctly.

    <script lang="ts">
	import { Carta, MarkdownEditor } from 'carta-md';
	// Component default theme
	import 'carta-md/default.css';

	const carta = new Carta({
		// Remember to use a sanitizer to prevent XSS attacks
		// sanitizer: mySanitizer
	});

	let value = $state('');
</script>

<MarkdownEditor bind:value {carta} />

<style>
	/* Or in global stylesheet */
	/* Set your monospace font */
	/* Required to have the editor working correctly! */
	:global(.carta-font-code) {
		font-family: '...', monospace;
		font-size: 1.1rem;
		line-height: 1.1rem;
		letter-spacing: normal;
	}
</style>