| name | adding-markdown-highlighted-comments |
| description | Use when adding responses to markdown documents with user-highlighted comments, encountering markup errors, or unsure about mark tag placement - ensures proper model-highlight formatting with required attributes and correct placement within markdown elements |
Adding markdown Highlighted Comments
Overview
Add AI responses to markdown documents using standardized highlighted markup that tracks authorship, timestamps, and relationships between comments.
Core principle: Marks go INSIDE markdown formatting. Each line/paragraph gets separate marks. Code blocks are NEVER wrapped in marks (prevents rendering issues).
When to Use
Use this skill when:
- User asks you to add comments/responses to an markdown document
- Document contains
<mark class="user-highlight"> tags
- You need to respond to highlighted user comments
- Working with documents that have highlighted sections
Don't use for:
- Plain markdown without highlight markup
- Chat-only responses
- Documents without existing highlight infrastructure
Required Markup Structure
Class and Attributes
ALWAYS use exactly:
<mark class="model-highlight"
data-model="claude-sonnet-4-20250514"
data-created="2025-01-06T10:30:00"
data-modified="2025-01-06T10:30:00"
data-id="mark-1736163000-a1b2c3"
data-group-id="response-202501061030">
Required attributes - no exceptions:
class="model-highlight" (exactly this, not claude-highlight or claude-response)data-model - your exact model IDdata-created - ISO 8601 timestampdata-modified - ISO 8601 timestamp (same as created for new)data-id - unique: mark-TIMESTAMP-RANDOMdata-group-id - group identifier: response-YYYYMMDDHHMM
Do NOT invent attributes:
- ❌
data-in-reply-to
- ❌
data-user-id
- ❌ Any other custom attributes
Group Delimiters
ALWAYS wrap your entire response:
[Your marked-up response here]
Missing delimiters = violation.
Mark Placement Rules
Rule 1: Marks INSIDE Formatting
✅ CORRECT: **<mark ...>Bold text</mark>**
❌ WRONG: <mark ...>**Bold text**</mark>
✅ CORRECT: *<mark ...>Italic text</mark>*
❌ WRONG: <mark ...>*Italic text*</mark>
✅ CORRECT: • **<mark ...>Item</mark>**<mark ...> - description</mark>
❌ WRONG: • <mark ...>**Item** - description</mark>
Rule 2: Separate Marks Per Line/Paragraph
One sentence = one mark. Multiple sentences = multiple marks.
✅ CORRECT:
**<mark ...>First sentence here.</mark>**
**<mark ...>Second sentence here.</mark>**
❌ WRONG - Multi-sentence paragraph:
**<mark ...>First sentence here. Second sentence here.</mark>**
❌ WRONG - Multi-paragraph:
**<mark ...>First paragraph here.
Second paragraph here.</mark>**
For bullet lists, use • character, not markdown - syntax:
✅ CORRECT:
• **<mark ...>Item title</mark>**<mark ...> - description text</mark>
• **<mark ...>Second item</mark>**<mark ...> - more description</mark>
❌ WRONG - Using markdown dash:
<mark ...>- Item title - description text</mark>
❌ WRONG - Mark outside bullet:
<mark ...>• Item title - description</mark>
Rule 3: Code Blocks - NEVER Wrap in Marks
Code blocks must NEVER be wrapped in <mark> tags. This breaks markdown rendering.
✅ CORRECT - No marks on code blocks:
```typescript
function example() {
return true;
}
❌ WRONG - Wrapping code block breaks rendering:
<mark ...>```typescript
function example() {
return true;
}
❌ WRONG - Marks inside code block:
```typescript
<mark ...>function example() {
return true;
}</mark>
Why: Wrapping code blocks in <mark> tags strips the code block presentation in Obsidian and other markdown renderers, turning formatted code into plain text.
What to do instead: Place code blocks in your response WITHOUT any mark tags. The code block will still be part of your response within the group delimiters.
Note about inline code: Inline code (single backticks like function()) within sentences SHOULD be marked as part of the sentence: Use the validateEmail() function. This rule applies only to code blocks (triple backticks).
Rule 4: No Spaces Between Adjacent Marks
✅ CORRECT: </mark><mark ...>
❌ WRONG: </mark> <mark ...>
Placement in Document
Find Comment Group
- Scan for user comments (
user-highlight marks)
- Group related comments:
- Comments in same list
- Comments separated by 1-2 lines
- Comments under same heading
- Find LAST comment in group
Insert Response
Place your response:
- ✅ AFTER the last user comment in the group
- ✅ BEFORE next unhighlighted section/heading
- ❌ NOT in the middle of user comment group
- ❌ NOT overwriting existing content
Common Mistakes
| Mistake | Fix |
|---|
class="claude-highlight" | Use class="model-highlight" exactly |
class="claude-response" | Use class="model-highlight" exactly |
**<mark>text</mark>** | Put mark inside: **<mark>text</mark>** |
| Multi-paragraph single mark | Create separate mark per paragraph |
| Wrapping code blocks in marks | Never wrap code blocks - breaks rendering |
| Missing group delimiters | Always add <!-- group-id:... --> wrapping |
| Inventing attributes | Only use the 6 required attributes |
Quick Reference
Every response needs:
- ☐ Group delimiters with matching group-id
- ☐ Each line/paragraph has separate mark tags
- ☐ Marks INSIDE markdown formatting (bold, italic, bullets)
- ☐ Code blocks: NEVER wrap in marks (prevents rendering issues)
- ☐ All 6 required attributes on every mark
- ☐
class="model-highlight" (not any other variation)
- ☐ No spaces between adjacent mark tags
- ☐ Placed after last user comment, before next approved section
Workflow
1. Read document to locate user comments
2. Identify comment group (all related comments)
3. Find last comment in group
4. Add group delimiter: <!-- group-id:response-YYYYMMDDHHMM -->
5. Write response with proper mark tags
6. Add closing delimiter: <!-- /group-id:response-YYYYMMDDHHMM -->
7. Verify placement (after comments, before approved content)
Complete Example
User comments:
**<mark class="user-highlight" data-created="..." data-modified="..." data-id="mark-1">Question 1?</mark>**
**<mark class="user-highlight" data-created="..." data-modified="..." data-id="mark-2">Question 2?</mark>**
Your response:
<!-- group-id:response-202501061030 -->
**<mark class="model-highlight" data-model="claude-sonnet-4-20250514" data-created="2025-01-06T10:30:00" data-modified="2025-01-06T10:30:00" data-id="mark-1736163000-abc" data-group-id="response-202501061030">Answer to question 1 here.</mark>**
**<mark class="model-highlight" data-model="claude-sonnet-4-20250514" data-created="2025-01-06T10:30:05" data-modified="2025-01-06T10:30:05" data-id="mark-1736163005-def" data-group-id="response-202501061030">Answer to question 2 here.</mark>**
```typescript
function handleTokenExpiration() {
// implementation
}
## Red Flags - STOP and Fix
If you catch yourself:
- Using `claude-highlight` or `claude-response` class
- Putting marks outside `**bold**` or `*italic*`
- Creating one mark for multiple sentences (even in same paragraph)
- Creating one mark for multiple paragraphs
- Using markdown `-` instead of `•` bullet character
- Putting marks around entire bullet including `•`
- Wrapping code blocks in `<mark>` tags
- Putting marks inside code block content
- Skipping group delimiters "to save time"
- Inventing new attributes like `data-in-reply-to`
- Adding spaces between adjacent mark tags
- Omitting bold formatting to "save time"
**All of these mean: Wrong markup. Fix before proceeding.**
## Common Rationalizations That Mean You're Failing
| Excuse | Reality |
|--------|---------|
| "Multi-sentence is more readable" | Wrong. One sentence = one mark. No exceptions. |
| "Markdown bullets are standard" | Wrong. Use `•` character, not `-` syntax. |
| "Skipping bold saves time" | Wrong. Match user formatting exactly. |
| "I'll fix formatting later" | Wrong. Fix now or you'll forget. |
| "Close enough under pressure" | Wrong. Pressure doesn't excuse violations. |
| "The skill doesn't apply here" | Wrong. If document has highlights, skill applies. |
| "Code blocks should be highlighted too" | Wrong. Wrapping breaks rendering. Never wrap code blocks. |
| "Just this small code snippet" | Wrong. ALL code blocks stay unwrapped, regardless of size. |
| "It works in my editor" | Wrong. Breaks in Obsidian and other renderers. Never wrap. |
**All of these mean: You're rationalizing. Follow the rules.**
