CriticMarkup

CriticMarkup provides a way to track changes, make suggestions, and add comments to documents using simple, human-readable markup syntax.

Overview

CriticMarkup enables:

• Track changes - Show additions, deletions, and substitutions
• Comments - Add inline annotations and notes
• Highlights - Mark important sections
• Collaboration - Review and suggest edits
• Version control friendly - Plain text markup
• Visual feedback - Clear styling for different change types

Configuration

Enable CriticMarkup in mkdocs.yml:

markdown_extensions:
  - pymdownx.critic

Advanced Configuration

markdown_extensions:
  - pymdownx.critic:
      mode: view    # view, accept, or reject

Configuration modes: - view - Show all markup with styling (default) - accept - Accept all changes, hide markup - reject - Reject all changes, show original

Basic Syntax

Additions

Use text to mark additions:

This is new text.

Result:

This is new text.

Deletions

Use text to mark deletions:

This is old text.

Result:

This is old text.

Substitutions

Use oldnew to mark replacements:

This is incorrectcorrect text.

Result:

This is incorrectcorrect text.

Comments

Use comment to add comments:

This needs review.Please verify this information

Result:

This needs review.Please verify this information

Highlights

Use text to highlight:

This is important information.

Result:

This is important information.

Combined with Comments

Use textcomment to highlight with a comment:

This is criticalMust be addressed before release for the project.

Result:

This is criticalMust be addressed before release for the project.

Advanced Usage

Complex Edits

Combining multiple changes:

The oldnew system now supports deprecated featuresMigration guide needed and enhanced security.

Result:

The oldnew system now supports deprecated featuresMigration guide needed and enhanced security.

Paragraph-Level Changes

This entire paragraph is being removed because it contains outdated information
about the legacy system that is no longer relevant.



This new paragraph explains the modern approach using current best practices
and updated technologies that better serve our users' needs.

Nested Changes

This is a completely {==new==}{>>Emphasize this<<} feature in version 2.0.

Result:

This is a completely {new}{>>Emphasize this<<} feature in version 2.0.

Practical Examples

Code Review

def calculate_total(items):
    czjqqkd:72total = 0
    for item in items:
        total += item.priceczjqqkd:73
    czjqqkd:74return sum(item.price for item in items)czjqqkd:75czjqqkd:76

Documentation Updates

## Installation

Download the installer from our websiteInstall using pip:


1. Download the .exe file
2. Run the installer
3. Follow the wizard



```bash
pip install our-package

Updated to use standard Python packaging

### API Changes

```markdown
### Authentication

The API now uses API keysOAuth 2.0 tokens for authentication.


Include your API key in the header:
`X-API-Key: your-key-here`



Include your bearer token in the header:
`Authorization: Bearer your-token-here`


Breaking ChangeRequires migration by April 1st

Styling

Default Styles

CriticMarkup elements are styled by default:

• Additions: Green background/text
• Deletions: Red strikethrough
• Substitutions: Combined styling
• Comments: Yellow note style
• Highlights: Yellow background

Custom CSS

/* Custom CriticMarkup styling */
.critic.addition {
    background-color: #d4f4dd;
    color: #22863a;
    text-decoration: none;
}

.critic.deletion {
    background-color: #ffeef0;
    color: #d73a49;
    text-decoration: line-through;
}

.critic.substitution {
    background-color: #fff5b1;
    color: #856404;
}

.critic.comment {
    background-color: #fff3cd;
    border: 1px solid #ffeeba;
    border-radius: 0.25rem;
    padding: 0.1rem 0.4rem;
    margin: 0 0.2rem;
    font-size: 0.85em;
}

.critic.highlight {
    background-color: #fff3cd;
    padding: 0.1rem 0.2rem;
}

/* Print styles */
@media print {
    .critic.comment {
        display: none;
    }

    .critic.deletion {
        display: none;
    }
}

Use Cases

Editorial Workflow

# Article Title

By Jane SmithAdd author bio

## Introduction

The widgetgadget industry has significantly evolved over the past decade. Traditional manufacturing methods are becoming obsolete. Modern techniques offer greater efficiency and sustainability.

Key findings:Needs data verification

- Market growth: 15%23% annually
- Customer satisfaction: 92% positive
- Environmental impact: High carbon footprintCarbon neutral by 2025

Technical Documentation

## Configuration


### Legacy Method
Edit the config.xml file manually:
```xml
<setting name="debug">true</setting>

New Method

Use the configuration API:

config.set('debug', True)
config.save()

Migration script available in tools/migrate.py

### Collaborative Review

```markdown
## Proposal

We should immediately migrate to the new platform by end of yearby Q2.

### Benefits

1. Cost reductionEstimated 30% savings
2. Improved performance
3. Enhanced security features
4. Legacy system compatibilityNo longer needed

### Risks

- Training requirements
- High upfront costsModerate investment needed
- Migration complexityAddressed by phased approach

Integration with Version Control

Git Workflow

CriticMarkup works well with Git:

1. Make changes with CriticMarkup
2. Commit with markup visible
3. Review in pull request
4. Accept/Reject changes
5. Clean markup before merge

Review Process

# Create feature branch
git checkout -b doc-updates

# Edit with CriticMarkup
# Commit changes
git add docs/
git commit -m "docs: Add proposed changes with CriticMarkup"

# After review, accept changes
# Update mkdocs.yml to mode: accept
# Or manually clean markup

Best Practices

1. Clear Context

Provide context for changes:

❌ Bad:
The numbervalue should be updated.

✅ Good:
The numbervalueChanged for consistency with API docs should be updated.

2. Atomic Changes

Keep related changes together:

✅ Good:
The old method is deprecatedUse the new async method instead

❌ Bad:
The old method Use the new is deprecated async method instead

3. Comment Wisely

Add meaningful comments:

✅ Good:
TODO: Add code example after API finalization

❌ Bad:
Fix this

4. Clean Up

Remove markup after acceptance:

Before: This is new content.
After: This is new content.

Advanced Features

Conditional Display

Use CSS to show/hide based on context:

/* Hide comments in production */
.production .critic.comment {
    display: none;
}

/* Show only in review mode */
.review-mode .critic {
    border: 1px dashed #666;
}

JavaScript Integration

Add interactivity:

// Toggle change visibility
document.querySelectorAll('.critic').forEach(element => {
    element.addEventListener('click', function() {
        this.classList.toggle('expanded');
    });
});

// Accept all changes
function acceptAllChanges() {
    document.querySelectorAll('.critic.deletion').forEach(el => el.remove());
    document.querySelectorAll('.critic.addition').forEach(el => {
        el.outerHTML = el.innerHTML;
    });
}

Export Options

Create different versions:

# Export with changes visible
mkdocs build

# Export clean version
# Set mode: accept in config
mkdocs build -f mkdocs-clean.yml

Common Patterns

Version Comparison

## Version 1.02.0 Changes

- Removed deprecated API endpoints
- Added GraphQL support
- ModifiedEnhanced authentication system
- Breaking changesSee migration guide

Review Checklist

## Review Items

- [ ] Technical accuracySME review needed
- [x] Grammar and spelling
- [ ] Code examples tested
- [ ] Outdated references removed
- [ ] ScreenshotsDiagrams updated

Progressive Enhancement

## Feature Description

Basic functionality includes limited options.

Advanced users can access:
- Custom configurations
- API integrations  
- Automation featuresPremium tier only

See Also

• CriticMarkup Specification
• PyMdown Extensions - Critic
• Collaborative Documentation
• Version Control Integration