---
id: 12214
title: Document the canonical PR + Discussion markdown grammar by the syncers
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-opus-ada
createdAt: '2026-05-30T17:26:27Z'
updatedAt: '2026-05-30T19:49:11Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12214'
author: neo-opus-ada
commentsCount: 0
parentIssue: 12204
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-30T19:49:11Z'
---
# Document the canonical PR + Discussion markdown grammar by the syncers

## Context
Part of epic #12207. The portal PR/Discussion parsers (subs 7, 8) need a single source of truth for the entry-header grammar the syncers emit, or each will re-derive (and get it wrong).

## The Fix
Document, adjacent to `PullRequestSyncer.mjs` / `DiscussionSyncer.mjs`, the canonical grammar:
- backtick-wrapped entry headers: `` ### `@user` commented on <ISO_Z> `` and `` ### `@user` (STATE) reviewed on <ISO_Z> ``;
- entries are delimited by the **next header**, NOT by bare `---` (which appears inside bodies);
- the discussion comment grammar (same backtick header form).

Corrects the earlier non-backtick assumption. The portal parser regexes (subs 7/8) cite this doc.

## Acceptance Criteria
- [ ] A grammar reference exists next to the syncers; subs 7/8 reference it.

## Related
Epic #12207. Source-of-truth for subs 7 + 8 (no code dependency; land before/alongside them).

## Timeline

- 2026-05-30T17:26:28Z @neo-opus-ada added the `documentation` label
- 2026-05-30T17:26:28Z @neo-opus-ada added the `enhancement` label
- 2026-05-30T17:26:28Z @neo-opus-ada added the `ai` label
- 2026-05-30T17:30:19Z @neo-opus-ada added parent issue #12207
- 2026-05-30T17:31:33Z @neo-opus-ada marked this issue as being blocked by #12213
- 2026-05-30T17:35:00Z @neo-opus-ada removed parent issue #12207
- 2026-05-30T17:35:01Z @neo-opus-ada added parent issue #12204
- 2026-05-30T17:35:51Z @neo-opus-ada removed the block by #12213
- 2026-05-30T19:25:58Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-30T19:31:22Z @neo-opus-ada cross-referenced by PR #12223
- 2026-05-30T19:36:33Z @neo-opus-ada referenced in commit `c44d3d1` - "docs(github-workflow): document canonical PR + Discussion markdown grammar (#12214)

Co-Authored-By: neo-opus-ada <neo-opus-ada@neomjs.com>"
- 2026-05-30T19:49:11Z @tobiu referenced in commit `d28791d` - "docs(github-workflow): document canonical PR + Discussion markdown grammar (#12214) (#12223)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-30T19:49:11Z @tobiu closed this issue
- 2026-05-31T18:28:40Z @neo-gpt cross-referenced by #12204

