carta/packages/carta-md
2023-11-07 12:13:26 +01:00
..
src fix: set correct role attribute 2023-11-07 12:13:26 +01:00
static convert to monorepo 2023-05-04 22:22:46 +02:00
.gitignore improved syntax highlighting 2023-07-14 08:49:16 +02:00
.prettierignore convert to monorepo 2023-05-04 22:22:46 +02:00
eslintignore convert to monorepo 2023-05-04 22:22:46 +02:00
package.json build(core): remove marked-mangle and gfmheadingids 2023-11-07 11:46:11 +01:00
README.md build(core): remove marked-mangle and gfmheadingids 2023-11-07 11:46:11 +01:00
svelte.config.js remove custom shj build 2023-08-01 19:18:45 +02:00
tsconfig.json remove custom shj build 2023-08-01 19:18:45 +02:00
vite.config.js convert to monorepo 2023-05-04 22:22:46 +02:00

logo

npm bundle license demo

Carta is a lightweight, fast and extensible Svelte Markdown editor and viewer, based on Marked. Check out the demo to see it in action. Differently from most editors, Carta includes neither ProseMirror nor CodeMirror, allowing for an extremely small bundle size and fast loading time.

Features

  • Keyboard shortcuts (extensible);
  • Toolbar (extensible);
  • Markdown syntax highlighting;
  • Scroll sync;
  • SSR compatible;
  • Katex support (plugin);
  • Slash commands (plugin);
  • Emojis, with included search (plugin);
  • Tikz support(plugin);
  • Attachment support(plugin);
  • Code blocks syntax highlighting (plugin).

Getting started

Warning

Sanitization is not dealt with by Carta. You need to provide a sanitizer in the options. Common sanitizers are isomorphic-dompurify (suggested) and sanitize-html.

Installation

Core package:

npm i carta-md

Plugins:

npm i @cartamd/plugin-name

Basic configuration

<script lang="ts">
	import { Carta, CartaEditor } from 'carta-md';
	// Component default theme
	import 'carta-md/default-theme.css';
	// Markdown input theme (Speed Highlight)
	import 'carta-md/light.css';

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

<CartaEditor {carta} />

<style>
	/* Or in global stylesheet */
	/* Set your custom monospace font */
	:global(.carta-font-code) {
		font-family: '...', monospace;
	}
</style>

Editor component exported properties:

Name Type Description
carta Carta Carta Editor
theme string For custom css themes, see below for more
value string Markdown input
placeholder string Placeholder text for textarea
mode 'tabs' | 'split' | 'auto' Tabs settings
disableToolbar boolean Option to disable the toolbar

Plugins

Each plugin's readme includes a guide on its use.

Name Description
plugin-math Katex support
plugin-slash Slash commands support
plugin-emoji Emojis support, including inline search
plugin-code Code blocks syntax highlighting
plugin-tikz TikZ support using TikZJax
plugin-attachment Attachments support

Themes customization

By using the theme property in CartaEditor and CartaPreview you can change their classes to carta-editor__{theme} and carta-viewer__{theme}.

Check out the default theme to customize it.

If you are using a plugin, look at its readme for its customization.

Markdown highlighting is done using Speed Highlight JS, here you can find more themes.

You can find complete Markdown stylesheet online. For example github-markdown-css(used in the demo), or tailwind-typography.

Extensibility

Options

Carta options:

Name Type Description
extensions CartaExtension[] Editor/viewer extensions
rendererDebounce number Renderer debouncing timeout, in ms (def. 300ms)
disableShortcuts DefaultShortcutId[] | true Remove default shortcuts by ids
disableIcons DefaultIconId[] | true Remove default icons by ids
disablePrefixes DefaultPrefixId[] | true Remove default prefixes by ids
historyOptions Partial<CartaHistoryOptions> History (Undo/Redo) options
sanitizer (html: string) => string HTML sanitizer

You can easily extend Carta by creating custom plugins. Here are all the CartaExtension properties:

Name Type Description
markedExtensions marked.MarkedExtension[] Marked extensions, more on that here
shortcuts KeyboardShortcut[] Additional keyboard shortcuts
icons CartaIcon[] Additional icons
prefixes Prefix[] Additional prefixes
listeners CartaListener[] Textarea event listeners
components CartaExtensionComponents Additional components, that will be put after the editor. All components are given a carta: Carta. prop The editor has a relative position, so you can position elements absolutely
highlightRules HighlightRule[] Custom markdown highlight rules. See Speed-Highlight Wiki.
onLoad (data: { carta:Carta, ... }) => void Use this callback to execute code when one Carta instance loads the extension.

If you created a plugin and want to share it, you can open an issue and we will consider sponsoring it on this guide.

Contributions

Every contribution is well accepted. If you have a feature request you can open a new issue.

This package uses a pnpm workspace, so pnpm is required to download and put everything together properly.

Committing

This repository is commitizen friendly. To commit use:

npm run commit
# or, if you have commitizen installed globally
git cz