Skip to content

Commit 4c105f6

Browse files
cscheidcscheid
committed
attempt to make claude remember red-light/green-light tdd
1 parent 17e24ef commit 4c105f6

File tree

3 files changed

+157
-1
lines changed

3 files changed

+157
-1
lines changed

‎CLAUDE.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,24 @@
22

33
The main documentation for this repository is located at:
44
[crates/quarto-markdown-pandoc/CLAUDE.md](crates/quarto-markdown-pandoc/CLAUDE.md)
5+
6+
## **CRITICAL - TEST-DRIVEN DEVELOPMENT**
7+
8+
When fixing ANY bug:
9+
1. **FIRST**: Write the test
10+
2. **SECOND**: Run the test and verify it fails as expected
11+
3. **THIRD**: Implement the fix
12+
4. **FOURTH**: Run the test and verify it passes
13+
14+
**This is non-negotiable. Never implement a fix before verifying the test fails.**
15+
16+
## General Instructions
17+
518
- in this repository, "qmd" means "quarto markdown", the dialect of markdown we are developing. Although we aim to be largely compatible with Pandoc, it is not necessarily the case that a discrepancy in the behavior is a bug.
619
- the qmd format only supports the inline syntax for a link [link](./target.html), and not the reference-style syntax [link][1].
720
- Always strive for test documents as small as possible. Prefer a large number of small test documents instead of small number of large documents.
821
- When fixing bugs, always try to isolate and fix one bug at a time.
9-
- When fixing bugs using tests, run the failing test before attempting to fix issues. This helps ensuring that tests are exercising the failure as expected, and fixes actually fix the particular issue.
22+
- **CRITICAL - TEST FIRST**: When fixing bugs using tests, you MUST run the failing test BEFORE implementing any fix. This is non-negotiable. Verify the test fails in the expected way, then implement the fix, then verify the test passes.
1023
- If you need to fix parser bugs, you will find use in running the application with "-v", which will provide a large amount of information from the tree-sitter parsing process, including a print of the concrete syntax tree out to stderr.
1124
- use "cargo run --" instead of trying to find the binary location, which will often be outside of this crate.
1225
- when calling shell scripts, ALWAYS BE MINDFUL of the current directory you're operating in. use `pwd` as necessary to avoid confusing yourself over commands that use relative paths.

‎docs/syntax/editorial-marks.qmd‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: "Editorial Marks"
3+
---
4+
5+
## Overview
6+
7+
Editorial marks allow you to annotate your text with suggestions, highlights, and comments during the editing and review process. In `quarto-markdown`, these marks use a special bracket syntax and are converted to Pandoc AST spans with specific CSS classes that can be styled or processed by filters.
8+
9+
## Syntax
10+
11+
Editorial marks use a square bracket syntax with special marker characters:
12+
13+
- `[!! text]` - Highlight
14+
- `[++ text]` - Insertion suggestion
15+
- `[-- text]` - Deletion suggestion
16+
- `[>> text]` - Comment
17+
18+
The opening bracket is followed by two marker characters, then a space, and then the content to be marked. The mark is closed with a closing bracket.
19+
20+
## Conversion to Pandoc AST
21+
22+
When converted to Pandoc AST, editorial marks become `Span` elements with specific CSS classes:
23+
24+
- `[!! ...]` → `Span ("", ["quarto-highlight"], []) [...]`
25+
- `[++ ...]` → `Span ("", ["quarto-insert"], []) [...]`
26+
- `[-- ...]` → `Span ("", ["quarto-delete"], []) [...]`
27+
- `[>> ...]` → `Span ("", ["quarto-edit-comment"], []) [...]`
28+
29+
These classes can be used to apply styling in HTML output or to process the marks with Pandoc filters.
30+
31+
## Examples
32+
33+
### Highlight
34+
35+
Use `[!! text]` to highlight important sections that need attention:
36+
37+
This paragraph contains [!! an important section] that should be reviewed.
38+
39+
```markdown
40+
This paragraph contains [!! an important section] that should be reviewed.
41+
```
42+
43+
### Insertion Suggestion
44+
45+
Use `[++ text]` to suggest text that should be added:
46+
47+
The document needs [++ additional context here] to be complete.
48+
49+
```markdown
50+
The document needs [++ additional context here] to be complete.
51+
```
52+
53+
### Deletion Suggestion
54+
55+
Use `[-- text]` to suggest text that should be removed:
56+
57+
This sentence has [-- unnecessary words] that can be deleted.
58+
59+
```markdown
60+
This sentence has [-- unnecessary words] that can be deleted.
61+
```
62+
63+
### Comment
64+
65+
Use `[>> text]` to add editorial comments or notes:
66+
67+
The conclusion [>> needs more supporting evidence] requires revision.
68+
69+
```markdown
70+
The conclusion [>> needs more supporting evidence] requires revision.
71+
```
72+
73+
### Multiple Marks in One Paragraph
74+
75+
You can use multiple editorial marks in a single paragraph:
76+
77+
This paragraph has [!! a highlight], [++ an insertion], [-- a deletion], and [>> a comment] all together.
78+
79+
```markdown
80+
This paragraph has [!! a highlight], [++ an insertion], [-- a deletion], and [>> a comment] all together.
81+
```
82+
83+
### Nested Formatting
84+
85+
Editorial marks can contain other inline formatting:
86+
87+
The section needs [++ **bold text** and *italic text*] to emphasize the point.
88+
89+
```markdown
90+
The section needs [++ **bold text** and *italic text*] to emphasize the point.
91+
```
92+
93+
## Use Cases
94+
95+
Editorial marks are particularly useful for:
96+
97+
- **Collaborative editing**: Team members can suggest changes without directly modifying the text
98+
- **Review workflows**: Reviewers can highlight issues and suggest improvements
99+
- **Track changes**: Similar to word processor track changes, but in plain text
100+
- **Editorial comments**: Editors can leave notes without disrupting the flow of the document
101+
102+
## Processing Editorial Marks
103+
104+
Since editorial marks are converted to spans with CSS classes, you can:
105+
106+
1. **Style them in HTML output**: Use CSS to visually distinguish different mark types
107+
2. **Process with Lua filters**: Write Pandoc Lua filters to convert marks to other formats
108+
3. **Accept/reject suggestions**: Build tools to process insertion and deletion suggestions
109+
4. **Generate reports**: Extract all comments and highlights for review
110+
111+
### Example CSS Styling
112+
113+
```css
114+
.quarto-highlight {
115+
background-color: yellow;
116+
}
117+
118+
.quarto-insert {
119+
color: green;
120+
text-decoration: underline;
121+
}
122+
123+
.quarto-delete {
124+
color: red;
125+
text-decoration: line-through;
126+
}
127+
128+
.quarto-edit-comment {
129+
color: blue;
130+
font-style: italic;
131+
}
132+
```
133+
134+
## Availability
135+
136+
Editorial marks are currently only available when using `quarto-markdown-pandoc`. This syntax will be integrated into Quarto's markdown processing in future releases.
137+
138+
## Limitations
139+
140+
- Editorial marks only support inline content, not block-level elements
141+
- The marker characters (`!!`, `++`, `--`, `>>`) must be followed by a space
142+
- Editorial marks cannot be nested within each other

‎docs/syntax/index.qmd‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,5 @@ The features documented here are currently under development. The syntax and beh
1111
## Available Features
1212

1313
- [Definition Lists](definition-lists.qmd) - Create definition lists using an embedded markdown DSL
14+
- [Editorial Marks](editorial-marks.qmd) - Annotate text with highlights, insertions, deletions, and comments
1415
- [Footnotes](footnotes.qmd) - Add footnotes with inline or fenced block syntax

0 commit comments

Comments
 (0)