Skip to content

Commit 592120a

Browse files
respencer-nclclaude
andcommitted
Reorder navigation, single-source EBNF grammar, enlarge logo
- Reorder nav tabs: RIDDL → Synapify → MCP → IDE Support → About - Rename OSS section to "IDE Support" for clarity - Single-source EBNF grammar from riddl-language jar - Auto-extracts on `sbt update` when jar is newer - Uses MkDocs snippets to include .ebnf file - Increase header logo size via CSS - Update sbt-ossuminc to 1.2.4 - Add GitHub Packages resolver for riddl dependency Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 13d5b16 commit 592120a

9 files changed

Lines changed: 599 additions & 371 deletions

File tree

NOTEBOOK.md

Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,31 @@ sections are documented with proper RIDDL syntax highlighting.
77

88
**Completed (2026-01-28):**
99

10+
- Navigation reordered: RIDDL → Synapify → MCP → IDE Support → About
11+
- Renamed "OSS" section to "IDE Support" in navigation
12+
- EBNF grammar single-sourced from riddl-language jar (auto-extracts on
13+
`sbt update`)
14+
- Header logo size increased
1015
- MCP Server URL updated to `https://mcp.ossuminc.com/mcp/v1/` in all guides
1116
- Added GitHub Copilot CLI integration guide (`docs/MCP/github-copilot.md`)
1217
- Strategic site improvements Phase 1 (quickstart, examples gallery, SEO,
1318
edit links, PWA support, about page, playground placeholder)
1419
- RIDDL Pygments lexer with custom color scheme
1520
- Comprehensive editorial review
1621
- CI workflow with lexer installation
22+
- Updated sbt-ossuminc to 1.2.4
1723

1824
---
1925

2026
## Pending Tasks
2127

2228
### Before Production
2329

24-
| Task | Notes |
25-
|--------------------------------|----------------------------------------------------------------|
26-
| Update release download links | When final releases are published |
27-
| Implement playground | Integrate Monaco + MCP server validation |
28-
| Remove "Coming Soon" warnings | When MCP server goes live (~early 2026) |
29-
| Single source for EBNF Grammar | Depend on riddl-language which contains the EBNF as a resource |
30+
| Task | Notes |
31+
|--------------------------------|--------------------------------------------|
32+
| Update release download links | When final releases are published |
33+
| Implement playground | Integrate Monaco + MCP server validation |
34+
| Remove "Coming Soon" warnings | When MCP server goes live (~early 2026) |
3035

3136
### Deferred Strategic Improvements (Soon)
3237

@@ -56,28 +61,22 @@ sections are documented with proper RIDDL syntax highlighting.
5661
|------|------|-------|
5762
| Type examples | `references/language-reference.md` | Add specialized examples |
5863
| Future work review | `future-work/` | Update for current roadmap |
59-
| EBNF grammar validation | `references/ebnf-grammar.md` | See details below |
6064
| Synapify generation docs | `synapify/generation.md` | Use preserved config |
6165

6266
---
6367

6468
## Task Details
6569

66-
### EBNF Grammar Validation
70+
### EBNF Grammar Single-Sourcing
6771

68-
The EBNF grammar (`docs/riddl/references/ebnf-grammar.md`) is derived from the
69-
official fastparse grammar in the riddl module. It must accurately reflect the
70-
rules accepted by the parser.
72+
The EBNF grammar is now automatically extracted from the `riddl-language` jar:
7173

72-
**Known discrepancies found during editorial review:**
73-
- Missing `=` as alternative to `is` in type definitions
74-
- Missing `:` as alternative to `is` in field definitions (Scala-style syntax)
74+
- **Source**: `riddl/grammar/ebnf-grammar.ebnf` resource in riddl-language jar
75+
- **Target**: `docs/riddl/references/ebnf-grammar.ebnf`
76+
- **Trigger**: Runs automatically on `sbt update`
77+
- **Logic**: Only extracts if jar version is newer than local copy
7578

76-
**Validation approach:**
77-
1. Create a functional parser from the EBNF grammar
78-
2. Run it against all example RIDDL sources in the test suite
79-
3. Compare results with the fastparse parser
80-
4. Revise EBNF until there are no discrepancies
79+
To manually extract: `sbt extractEbnf`
8180

8281
### Synapify Generation Configuration
8382

@@ -105,13 +104,15 @@ hugo {
105104

106105
| Decision | Rationale | Date |
107106
|----------|-----------|------|
107+
| EBNF single-sourced from jar | Keeps docs in sync with compiler grammar | 2026-01-28 |
108+
| Nav order: RIDDL first | Primary product should be most prominent | 2026-01-28 |
109+
| OSS renamed to IDE Support | Clearer purpose for visitors | 2026-01-28 |
108110
| RIDDL lexer colors from IDE tools | Consistency across VS Code, IntelliJ, docs | 2026-01-28 |
109111
| Lexer installed via pip in CI | Ensures syntax highlighting works in deployment | 2026-01-28 |
110112
| CSS overrides for dark/light | MkDocs Material uses CSS, not Pygments styles | 2026-01-28 |
111113
| Synapify four-panel layout | Left=tree, center=visual+text, right=metadata | 2026-01-26 |
112114
| riddlc validation-only | Code generation moved to Synapify | 2026-01-27 |
113115
| Separate MCP section | MCP distinct from IDE plugins; deserves own nav | 2026-01-21 |
114-
| URL placeholder pattern | `{{MCP_SERVER_URL}}` allows easy find/replace | 2026-01-21 |
115116

116117
---
117118

build.sbt

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,35 @@ lazy val developers: List[Developer] = List(
99
)
1010
)
1111

12+
// Task to extract EBNF grammar from riddl-language jar
13+
lazy val extractEbnf = taskKey[File]("Extract EBNF grammar from riddl-language jar if newer")
14+
1215
lazy val root = Root(
13-
"ossum-tech",
14-
"ossuminc",
15-
"com.ossum.doc",
16+
ghRepoName = "ossum-tech",
17+
ghOrgName = "ossuminc",
1618
startYr = 2025,
1719
devs = developers
18-
).settings(name := "ossum-tech")
20+
).configure(
21+
With.Scala3
22+
).settings(
23+
resolvers += "GitHub Package Registry" at "https://maven.pkg.github.com/ossuminc/riddl",
24+
libraryDependencies += "com.ossuminc" %% "riddl-language" % "1.1.2+",
25+
26+
// Define the extractEbnf task - automatically triggers update via dependencyClasspath
27+
extractEbnf := ExtractEbnf(
28+
baseDirectory.value,
29+
(Compile / dependencyClasspath).value.files,
30+
streams.value.log
31+
),
32+
33+
// Automatically extract EBNF after update resolves dependencies
34+
update := {
35+
val updateReport = update.value
36+
ExtractEbnf.fromUpdateReport(
37+
baseDirectory.value,
38+
updateReport,
39+
streams.value.log
40+
)
41+
updateReport
42+
}
43+
)

docs/OSS/index.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
2-
title: "Open Source Tools"
2+
title: "IDE Support"
33
description: >-
4-
Free and open source tools for RIDDL development. IDE extensions for
5-
IntelliJ and VS Code, authoring guides, and MCP server integration.
4+
IDE extensions for RIDDL development. Plugins for IntelliJ IDEA and
5+
VS Code with syntax highlighting, validation, and code completion.
66
---
7-
# Ossum Open Source Software
7+
# IDE Support for RIDDL
88

9-
Ossum Inc. provides open source tools for working with the RIDDL language.
10-
All software is free to use under the Apache License 2.0.
9+
Ossum Inc. provides IDE extensions for working with the RIDDL language.
10+
All tools are free and open source under the Apache License 2.0.
1111

1212
## IDE Extensions
1313

0 commit comments

Comments
 (0)