Carve for Sublime Text

Syntax highlighting for the Carve markup language in Sublime Text 3 and 4.

Files with a .crv extension are highlighted automatically.

This package is authored from the maintained Carve TextMate grammar (scope text.carve) so its scope names line up with existing color schemes.

Features

• Headings (# … ######)
• Inline mnemonics: /italic/, *bold*, _underline_, ~strike~, =highlight= (single =), {^sup^}, {,sub,}, `code`
• Links, autolinks (<https://...>, <a@b.com>), images, reference and cross-reference links, inline spans
• Lists, task lists (- [ ] / - [x]), ordered lists, definition lists (:)
• Block quotes (>)
• Fenced code with language plus the fence header "header" / [label] - and the code inside is highlighted with Sublime's own syntax for that language (python, js/ts, rust, go, php, ruby, sql, shell, yaml, json, html, css and ~35 more)
• Raw passthrough fences (```=html), kept verbatim and never highlighted as code
• Divs (:::) with admonition types and "title" / [label]
• Block and inline attributes ({#id .class key="val"})
• Tables with |, |= header rows, ^ rowspan, < colspan, and GFM |---| delimiter rows
• Footnotes ([^id])
• Math: inline $.. , display$$.. , andmath“ fences
• Frontmatter (---, ---toml, ---json), highlighted with the declared format's own syntax
• Mentions (@name), tags (#tag), symbols (:smile:)
• Critic markup ({+ins+}, {-del-}, {~a~>b~}, {#comment#})
• Line comments (%%) and block comments (%%%)

Install

Package Control

1. Open the command palette (Ctrl/Cmd+Shift+P).
2. Run Package Control: Install Package.
3. Search for Carve and install it.

Manual

1. Find your packages directory via Preferences > Browse Packages….
2. Create a folder named Carve inside it.
3. Copy the contents of this repository into that folder.

Recommended view settings

The package does not override any editor settings. Since Carve is prose-oriented markup, settings like these tend to work well - open a .crv file and pick Preferences > Settings - Syntax Specific to apply them for Carve files only:

{
    "tab_size": 2,
    "translate_tabs_to_spaces": true,
    "word_wrap": true,
    "spell_check": true,
    // Spell-check prose only: skip code spans, code blocks, raw passthrough,
    // math, links, and attribute values.
    "spelling_selector": "text.carve - markup.raw - meta.math - markup.underline.link - meta.attributes",
    "trim_trailing_white_space_on_save": false
}

trim_trailing_white_space_on_save matters more here than in most languages: trailing spaces inside a Carve code block are content and render inside <pre>.

Commands

Available from the command palette:

Both need the carve CLI on PATH for formatting (npm install -g @markup-carve/carve or cargo install carve-lang). Configure in Preferences > Package Settings:

{
    "carve_binary": "carve",
    "carve_format_on_save": false
}

Build system

With a .crv file open, Tools > Build (ctrl+b) runs carve lint and the reported problems are clickable, because carve prints file:line:column. Tools > Build With… offers the other variants: lint the whole project, carve fmt --check, carve fmt -w, render HTML to stdout or to a file, and an ANSI terminal preview.

Snippets

Tab triggers for the constructs that are tedious to type by hand: note (admonition), table, codegroup, listtable, figure (image + caption), deflist, fn (footnote + definition), xref, code, fm (frontmatter), math, spoiler. Typing an admonition or extension name (warning, tabs, toc, mermaid, …) also offers a completion that expands the whole fence.

Running the syntax tests

syntax_test_carve.crv uses Sublime's syntax-test format, and CI runs it on every push via SublimeText/syntax-test-action.

To run it locally without a GUI, use Sublime's headless test runner:

# match <BUILD> to your Sublime build (Help > About)
curl -sSLO https://download.sublimetext.com/st_syntax_tests_build_4200_x64.tar.xz
tar xf st_syntax_tests_build_4200_x64.tar.xz
cd st_syntax_tests
mkdir -p Data/Packages/Carve && cp -r /path/to/sublime-carve/* Data/Packages/Carve/
./syntax_tests

Fenced code embeds Sublime's bundled language syntaxes, so to exercise those assertions the runner also needs the default packages: download https://github.com/sublimehq/Packages/archive/v<BUILD>.tar.gz and copy its folders into Data/Packages/ (this is what CI's default_packages: binary does). Inside Sublime itself, the tests also run from Build With… > Syntax Tests.

License

MIT. See LICENSE.