.. | ||
src | ||
static | ||
.gitignore | ||
.prettierignore | ||
eslintignore | ||
package.json | ||
README.md | ||
svelte.config.js | ||
tsconfig.json | ||
vite.config.js |
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