Skip to content

Commit 20e9a0b

Browse files
respencer-nclclaude
respencer-ncl
and
claude
committed
Add RIDDL Pygments lexer for syntax highlighting
- Created riddl_lexer package with full tokenization support: - Definition keywords (domain, context, entity, etc.) - burnt orange - Control keywords (if, then, send, etc.) - burnt orange - Readability words (is, of, by, etc.) - yellow - Predefined types (String, Integer, UUID, etc.) - teal - Option values (event-sourced, aggregate, etc.) - green - Comments - gray italic - Strings - bright green - Markdown documentation lines - dim green italic - Punctuation - teal - Added custom Pygments style matching RIDDL IDE tools - Added MkDocs Material CSS overrides for dark/light themes - Lexer registers automatically via Pygments entry point - Fixed broken Synapify links in guides (wrong relative path depth) - Updated .gitignore for Python build artifacts Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 2c2b5ab commit 20e9a0b

10 files changed

Lines changed: 411 additions & 27 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@
66
/site/
77
/.ai/
88
.DS_Store
9+
*.egg-info/
10+
__pycache__/

‎NOTEBOOK.md‎

Lines changed: 26 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -212,9 +212,30 @@ Completed all 6 phases of the comprehensive documentation improvement:
212212
- [x] Completed Author's Guide
213213
- [x] Improved hierarchy diagram in concepts
214214

215+
### 2026-01-28: RIDDL Pygments Lexer
216+
217+
Created custom Pygments lexer for RIDDL syntax highlighting in MkDocs:
218+
219+
- [x] **Created `riddl_lexer/` package** with proper Python packaging
220+
- `lexer.py`: Full lexer implementation with all RIDDL token types
221+
- `__init__.py`: Package exports
222+
- `pyproject.toml`: Package configuration with Pygments entry point
223+
- [x] **Token categories implemented**:
224+
- Definition keywords (domain, context, entity, etc.) → `Keyword.Declaration`
225+
- Control keywords (if, then, send, etc.) → `Keyword`
226+
- Import keywords (include, import) → `Keyword.Namespace`
227+
- Readability words (is, of, by, etc.) → `Keyword.Pseudo`
228+
- Predefined types (String, Integer, etc.) → `Name.Builtin`
229+
- Option values (event-sourced, aggregate) → `Name.Constant`
230+
- Comments (// and /* */) → `Comment`
231+
- Strings and markdown docs → `String`
232+
- [x] **Tested with MkDocs** - all 20 RIDDL code blocks properly highlighted
233+
- [x] **Fixed broken Synapify links** in guides (wrong relative path depth)
234+
215235
## In Progress
216236

217-
Editorial review complete. All sections reviewed and fixed. Ready to commit.
237+
Working through lower-priority tasks in order: type examples, quick-start
238+
tutorial, future work review, EBNF grammar validation, Synapify generation docs.
218239

219240
## Pending Tasks
220241

@@ -225,15 +246,16 @@ Editorial review complete. All sections reviewed and fixed. Ready to commit.
225246
| Replace `{{MCP_SERVER_URL}}` | When public URL is available |
226247
| Update release download links | When final releases are published |
227248

228-
### Lower Priority
249+
### Lower Priority (in progress order)
229250

230251
| Task | File | Notes |
231252
|------|------|-------|
232-
| RIDDL Pygments lexer | New file | Custom syntax highlighting for code blocks |
253+
| ~~RIDDL Pygments lexer~~ | ~~`riddl_lexer/`~~ | ~~COMPLETED~~ |
233254
| Type examples | `references/language-reference.md` | Add specialized examples |
234-
| Future work review | `future-work/` | Update for current roadmap |
235255
| Quick-start tutorial | New file | Optional getting started guide |
256+
| Future work review | `future-work/` | Update for current roadmap |
236257
| EBNF grammar validation | `references/ebnf-grammar.md` | See details below |
258+
| Synapify generation docs | `synapify/generation.md` | Document using preserved config |
237259

238260
#### Synapify Generation Configuration Documentation
239261

@@ -255,25 +277,6 @@ hugo {
255277
}
256278
```
257279

258-
#### RIDDL Pygments Lexer Task
259-
260-
Create a custom Pygments lexer for RIDDL syntax highlighting in MkDocs code
261-
blocks. Currently `riddl` fenced code blocks render without syntax coloring.
262-
263-
**Implementation approach:**
264-
1. Create `riddl_lexer.py` with a `RiddlLexer` class extending `RegexLexer`
265-
2. Define token patterns for RIDDL keywords, types, strings, comments, etc.
266-
3. Register the lexer in `mkdocs.yml` or via a plugin
267-
4. Test with existing code examples in documentation
268-
269-
**Key token categories:**
270-
- Keywords: `domain`, `context`, `entity`, `handler`, `type`, `command`,
271-
`event`, `query`, `result`, `is`, `of`, `to`, `from`, `inlet`, `outlet`, etc.
272-
- Predefined types: `String`, `Number`, `Boolean`, `Date`, `Time`, `UUID`, etc.
273-
- Operators: `=`, `:`, `{`, `}`, `(`, `)`, `[`, `]`
274-
- Comments: `//` line comments, `/* */` block comments
275-
- Strings: quoted literals
276-
277280
#### EBNF Grammar Validation Task
278281

279282
The EBNF grammar (`docs/riddl/references/ebnf-grammar.md`) is derived from the

‎docs/riddl/guides/authors/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -538,7 +538,7 @@ riddlc validate mymodel.riddl
538538
riddlc --verbose validate mymodel.riddl
539539
```
540540

541-
Documentation generation will be available through [Synapify](../../../../synapify/index.md).
541+
Documentation generation will be available through [Synapify](../../../synapify/index.md).
542542

543543
### Common Validation Issues
544544

‎docs/riddl/guides/developers/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ riddl/
7474
- Option handling
7575
- Output formatting
7676

77-
**hugo** - Documentation generator (being migrated to [Synapify](../../../../synapify/index.md)):
77+
**hugo** - Documentation generator (being migrated to [Synapify](../../../synapify/index.md)):
7878

7979
- Converts RIDDL models to Hugo-compatible markdown
8080
- Generates diagrams (Mermaid)

‎docs/riddl/guides/implementors/ways-to-use-riddl.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,10 +106,10 @@ Once you have RIDDL integrated into your development workflow:
106106
to catch specification issues before they become implementation problems.
107107

108108
2. **Generate documentation**: Documentation generation will be available
109-
through [Synapify](../../../../synapify/index.md).
109+
through [Synapify](../../../synapify/index.md).
110110

111111
3. **Explore code generation**: Code generation from RIDDL models will also
112-
be available through [Synapify](../../../../synapify/index.md).
112+
be available through [Synapify](../../../synapify/index.md).
113113

114114
See the [riddlc documentation](../../tools/riddlc/index.md) for the full
115115
command reference.

‎docs/stylesheets/extra.css‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,59 @@
77
.md-tabs{
88
background-color: #272740;
99
}
10+
11+
/* RIDDL Syntax Highlighting - Dark Theme */
12+
[data-md-color-scheme="slate"] .language-riddl {
13+
/* Keywords - burnt orange */
14+
.k, .kd, .kr, .kn { color: #fa8b61; }
15+
/* Readability words - yellow */
16+
.kp { color: #b3ae60; }
17+
/* Predefined types - teal */
18+
.nb { color: #19c4bf; }
19+
/* Option values - green */
20+
.no { color: #57d07c; }
21+
/* Punctuation - teal */
22+
.p { color: #0da19e; }
23+
/* Comments - gray */
24+
.c1, .cm { color: #808080; font-style: italic; }
25+
/* Strings - bright green */
26+
.s2, .s1 { color: #98c379; }
27+
/* Markdown docs - dimmer green */
28+
.sd { color: #629755; font-style: italic; }
29+
/* String escapes - yellow */
30+
.se { color: #e0be35; }
31+
/* Identifiers - default light */
32+
.n { color: #a9b7c6; }
33+
/* Numbers - blue */
34+
.mi, .mf { color: #6897bb; }
35+
/* Errors - red */
36+
.err { color: #c41919; }
37+
}
38+
39+
/* RIDDL Syntax Highlighting - Light Theme */
40+
[data-md-color-scheme="default"] .language-riddl {
41+
/* Keywords - burnt orange (darker for light bg) */
42+
.k, .kd, .kr, .kn { color: #c75a20; }
43+
/* Readability words - olive */
44+
.kp { color: #7a7a30; }
45+
/* Predefined types - teal */
46+
.nb { color: #0d8a85; }
47+
/* Option values - green */
48+
.no { color: #2d8a4a; }
49+
/* Punctuation - teal */
50+
.p { color: #0a7a75; }
51+
/* Comments - gray */
52+
.c1, .cm { color: #707070; font-style: italic; }
53+
/* Strings - green */
54+
.s2, .s1 { color: #50873a; }
55+
/* Markdown docs - dimmer green */
56+
.sd { color: #3d6a30; font-style: italic; }
57+
/* String escapes - olive */
58+
.se { color: #9a8520; }
59+
/* Identifiers - dark */
60+
.n { color: #2b2b2b; }
61+
/* Numbers - blue */
62+
.mi, .mf { color: #4a6a9a; }
63+
/* Errors - red */
64+
.err { color: #a31515; }
65+
}

‎pyproject.toml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
[build-system]
2+
requires = ["setuptools>=61.0"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "riddl-pygments-lexer"
7+
version = "1.0.0"
8+
description = "Pygments lexer for RIDDL language syntax highlighting"
9+
readme = "README.md"
10+
license = {text = "Apache-2.0"}
11+
authors = [
12+
{name = "Ossum Inc.", email = "support@ossuminc.com"}
13+
]
14+
keywords = ["pygments", "lexer", "riddl", "syntax-highlighting"]
15+
classifiers = [
16+
"Development Status :: 4 - Beta",
17+
"Environment :: Plugins",
18+
"Intended Audience :: Developers",
19+
"License :: OSI Approved :: Apache Software License",
20+
"Operating System :: OS Independent",
21+
"Programming Language :: Python :: 3",
22+
"Programming Language :: Python :: 3.8",
23+
"Programming Language :: Python :: 3.9",
24+
"Programming Language :: Python :: 3.10",
25+
"Programming Language :: Python :: 3.11",
26+
"Programming Language :: Python :: 3.12",
27+
"Topic :: Text Processing :: Filters",
28+
"Topic :: Text Processing :: Markup",
29+
]
30+
requires-python = ">=3.8"
31+
dependencies = [
32+
"pygments>=2.0",
33+
]
34+
35+
[project.entry-points."pygments.lexers"]
36+
riddl = "riddl_lexer:RiddlLexer"
37+
38+
[project.entry-points."pygments.styles"]
39+
riddl = "riddl_lexer:RiddlStyle"
40+
41+
[project.urls]
42+
Homepage = "https://ossum.tech"
43+
Repository = "https://github.com/ossuminc/ossum.tech"
44+
45+
[tool.setuptools.packages.find]
46+
where = ["."]
47+
include = ["riddl_lexer*"]

‎riddl_lexer/__init__.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
"""
2+
RIDDL Language Lexer for Pygments
3+
4+
This module provides syntax highlighting for RIDDL (Reactive Interface to
5+
Domain Definition Language) files in MkDocs and other Pygments-based tools.
6+
"""
7+
8+
from .lexer import RiddlLexer
9+
from .style import RiddlStyle
10+
11+
__all__ = ['RiddlLexer', 'RiddlStyle']
12+
__version__ = '1.0.0'

0 commit comments

Comments
 (0)