README

Syntax highlighting grammars for the Djot markup language.

Included Grammars

TextMate Grammar

Note: As of Phiki v2.1.1, the Djot grammar is bundled with Phiki. For PHP projects, use Phiki directly - no separate grammar installation needed. This file is kept for backwards compatibility with existing Shiki/Node.js projects.

Location: textmate/djot.tmLanguage.json

Works with:

• Shiki (VitePress, Astro, etc.)
• VS Code (via TextMate support)
• TextMate and compatible editors
• IntelliJ/PhpStorm (via Djot plugin)

Usage with Shiki (Node.js)

import { createHighlighter } from 'shiki'
import djotGrammar from 'djot-grammars/textmate/djot.tmLanguage.json'

const highlighter = await createHighlighter({
  themes: ['github-light'],
  langs: [djotGrammar],
})

const html = highlighter.codeToHtml(code, { lang: 'djot', theme: 'github-light' })

Usage with VitePress

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import djotGrammar from 'djot-grammars/textmate/djot.tmLanguage.json'

export default defineConfig({
  markdown: {
    languages: [
      { ...djotGrammar, name: 'djot', aliases: ['dj'] },
    ],
  },
})

Usage with Phiki (PHP)

As of Phiki v2.1.1, Djot is bundled - just use it directly:

use Phiki\Phiki;

$phiki = new Phiki();
$html = $phiki->codeToHtml($djotCode, 'djot', 'github-light');

highlight.js Grammar

Location: highlightjs/djot.js

Works with highlight.js for client-side syntax highlighting.

Usage

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script src="path/to/djot-grammars/highlightjs/djot.js"></script>
<script>hljs.highlightAll();</script>

<pre><code class="language-djot">
# Hello World

This is *strong* and _emphasized_ text.
</code></pre>

Prism.js Grammar

Location: prismjs/djot.js

Works with Prism.js for client-side syntax highlighting.

Usage

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
<script src="path/to/djot-grammars/prismjs/djot.js"></script>

<pre><code class="language-djot">
# Hello World

This is *strong* and _emphasized_ text.
</code></pre>

Tiptap Integration

Location: tiptap/

WYSIWYG editor integration for Tiptap with Djot serialization.

Quick Start

import { Editor } from '@tiptap/core'
import { DjotKit, serializeToDjot } from 'djot-grammars/tiptap'

const editor = new Editor({
  element: document.getElementById('editor'),
  extensions: [DjotKit],
  onUpdate: ({ editor }) => {
    const djot = serializeToDjot(editor.getJSON())
    console.log(djot)
  },
})

Features

• DjotKit - All-in-one extension bundle with full Djot support
• Custom marks - Insert {+text+}, Delete {-text-}, Div containers :::
• Serializer - Convert editor content to Djot markup
• Tables, task lists, code blocks with language, images, links

See tiptap/README.md for full documentation. Demo.

External Grammars

These Djot grammars are maintained in other repositories:

Supported Syntax

All grammars support the full Djot specification plus djot-php enhancements:

Block Elements

• Headings (# Title through ###### Title)
• Code fences (``` with optional language)
• Div blocks (::: with optional class)
• Blockquotes (> text)
• Lists (bullets -, *, + and numbered 1., 1))
• Task lists (- [ ], - [x])
• Definition lists (: term)
• Tables (| cell | cell | with separator rows)
• Line blocks (| text for poetry/addresses)
• Horizontal rules (---, ***, ___)
• Block attributes ({.class #id key=value})

Inline Elements

• Strong (*bold*)
• Emphasis (_italic_)
• Highlight ({=text=})
• Insert ({+text+})
• Delete ({-text-})
• Superscript (^text^, {^text^})
• Subscript (~text~, {~text~})
• Inline code (`code`)
• Links ([text](url), [text][ref])
• Images (![alt](url))
• Autolinks (<https://...>, <user@example.com>)
• Footnotes ([^note] and [^note]: definition)
• Math ($ `code` $ and $$ `code` $$)
• Symbols (:name:)
• Spans with attributes ([text]{.class})
• Raw format markers (`code`{=html})
• Escape sequences (\*, \[, etc.)
• Hard line breaks (\ at end of line)
• Smart punctuation (---, --, ...)

djot-php Extensions

• Captions (^ caption text for images, tables, blockquotes)
• Fenced comments (%%% blocks)
• Inline comments ({% comment %})
• Table row/cell attributes (| cell |{.class})

Installation

NPM

npm install djot-grammars

Composer (PHP)

composer require php-collective/djot-grammars

Manual

Download the grammar files directly from this repository.

Comparison

Note: Phiki v2.1.1+ bundles the Djot grammar directly.

Testing

Run the test suite to validate all grammars:

npm run test:install  # Install test dependencies
npm test              # Run grammar tests

The test suite validates TextMate, highlight.js, and Prism.js grammars against a comprehensive Djot syntax fixture covering all language elements.

Contributing

Contributions are welcome! Please ensure any changes maintain compatibility with the Djot specification.

License

MIT License - see LICENSE for details.

Related Projects

• Djot - The Djot markup language
• djot-php - PHP implementation
• djot.js - JavaScript implementation
• djot-intellij - IntelliJ/PhpStorm plugin