adding-markdown-highlighted-comments

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 ID
• data-created - ISO 8601 timestamp
• data-modified - ISO 8601 timestamp (same as created for new)
• data-id - unique: mark-TIMESTAMP-RANDOM
• data-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:

<!-- group-id:response-202501061030 -->

[Your marked-up response here]

<!-- /group-id:response-202501061030 -->

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

1. Scan for user comments (user-highlight marks)
2. Group related comments:
   • Comments in same list
   • Comments separated by 1-2 lines
   • Comments under same heading
3. 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:

1. ☐ Group delimiters with matching group-id
2. ☐ Each line/paragraph has separate mark tags
3. ☐ Marks INSIDE markdown formatting (bold, italic, bullets)
4. ☐ Code blocks: NEVER wrap in marks (prevents rendering issues)
5. ☐ All 6 required attributes on every mark
6. ☐ class="model-highlight" (not any other variation)
7. ☐ No spaces between adjacent mark tags
8. ☐ 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.**