Release 2.2.0

Author: Roman505050

CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-02-18
+
+### Changed
+- **Refactored MD/MDX Fixer architecture** - Modular fixer system for better extensibility
+  - Split fixer logic into separate fixer classes in `fixers/` directory
+  - Created base `Fixer` class for all fixers to inherit from
+  - Each fixer type now has its own module:
+    - `InvalidJsxTagsFixer` - Fixes JSX tags starting with numbers
+    - `HtmlCommentsFixer` - Converts HTML comments to JSX comments
+    - `UnclosedTagsFixer` - Fixes unclosed void elements
+    - `InvalidAttributesFixer` - Converts HTML attributes to JSX
+    - `SelfClosingTagsFixer` - Fixes self-closing tag spacing
+    - `NumericEntitiesFixer` - Fixes malformed numeric HTML entities
+    - `JsxCurlyBracesFixer` - Escapes curly braces in code-like contexts
+  - `MarkdownFixer` now dynamically uses available fixers
+  - Fixers can be customized by passing a custom list to `MarkdownFixer`
+
+### Added
+- **Enhanced curly brace handling** - Improved JSX curly brace escaping
+  - Automatically converts single backticks to double backticks for inline code containing curly braces
+  - Wraps code-like patterns (e.g., `key:value:{variable}`) in backticks to prevent MDX interpretation
+  - Preserves Markdown compatibility while preventing MDX build errors
+  - Ignores curly braces inside code blocks (```mermaid, ```python, etc.)
+  - Fixes `ReferenceError: variable is not defined` errors in Docusaurus builds
+
+### Improved
+- Better code organization and maintainability
+- Easier to add new fixers by creating a new class inheriting from `Fixer`
+- More flexible fixer configuration
+
 ## [2.1.0] - 2026-01-04
 ### Added
 - Support for HTTPS authentication with PAT tokens

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docusync"
-version = "2.1.0"
+version = "2.2.0"
 description = "CLI tool for syncing documentation from multiple repositories for Docusaurus"
 readme = "README.md"
 requires-python = ">=3.12"

src/docusync/__init__.py

@@ -1,3 +1,3 @@
 """DocuSync - Documentation synchronization tool for Docusaurus sites."""
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"

src/docusync/fixers/__init__.py

@@ -0,0 +1,41 @@
+"""Fixers for Markdown/MDX files."""
+
+from typing import List
+
+from .base import Fixer
+from .html_comments import HtmlCommentsFixer
+from .invalid_attributes import InvalidAttributesFixer
+from .invalid_jsx_tags import InvalidJsxTagsFixer
+from .jsx_curly_braces import JsxCurlyBracesFixer
+from .numeric_entities import NumericEntitiesFixer
+from .self_closing_tags import SelfClosingTagsFixer
+from .unclosed_tags import UnclosedTagsFixer
+
+
+def get_all_fixers() -> List[Fixer]:
+    """Get all available fixers.
+
+    :returns: List of fixer instances
+    """
+    return [
+        InvalidJsxTagsFixer(),
+        HtmlCommentsFixer(),
+        UnclosedTagsFixer(),
+        InvalidAttributesFixer(),
+        SelfClosingTagsFixer(),
+        NumericEntitiesFixer(),
+        JsxCurlyBracesFixer(),
+    ]
+
+
+__all__ = [
+    "Fixer",
+    "get_all_fixers",
+    "InvalidJsxTagsFixer",
+    "HtmlCommentsFixer",
+    "UnclosedTagsFixer",
+    "InvalidAttributesFixer",
+    "SelfClosingTagsFixer",
+    "NumericEntitiesFixer",
+    "JsxCurlyBracesFixer",
+]

src/docusync/fixers/base.py

@@ -0,0 +1,23 @@
+"""Base class for all fixers."""
+
+from abc import ABC, abstractmethod
+from typing import Tuple
+
+
+class Fixer(ABC):
+    """Base class for all markdown fixers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the name of this fixer."""
+        pass
+
+    @abstractmethod
+    def fix(self, content: str) -> Tuple[str, int]:
+        """Apply the fix to content.
+
+        :param content: The content to fix
+        :returns: Tuple of (fixed_content, number_of_fixes_applied)
+        """
+        pass

src/docusync/fixers/html_comments.py

@@ -0,0 +1,54 @@
+"""Fixer for HTML comments."""
+
+import re
+from typing import Tuple
+
+from .base import Fixer
+
+
+class HtmlCommentsFixer(Fixer):
+    """Convert HTML comments to JSX comments in JSX context.
+
+    HTML comments <!-- --> can cause issues in MDX.
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the name of this fixer."""
+        return "HTML comments to JSX"
+
+    def fix(self, content: str) -> Tuple[str, int]:
+        """Convert HTML comments to JSX comments.
+
+        :param content: The content to fix
+        :returns: Tuple of (fixed_content, number_of_fixes_applied)
+        """
+        # Find HTML comments not in code blocks
+        in_code_block = False
+        lines = content.split("\n")
+        fixed_lines = []
+        fixes = 0
+
+        for line in lines:
+            # Track code blocks
+            if line.strip().startswith("```"):
+                in_code_block = not in_code_block
+                fixed_lines.append(line)
+                continue
+
+            if not in_code_block:
+                # Replace HTML comments with JSX comments
+                if "<!--" in line and "-->" in line:
+                    # Simple inline HTML comment
+                    new_line = re.sub(
+                        r"<!--\s*(.*?)\s*-->",
+                        r"{/* \1 */}",
+                        line,
+                    )
+                    if new_line != line:
+                        fixes += 1
+                        line = new_line
+
+            fixed_lines.append(line)
+
+        return "\n".join(fixed_lines), fixes

src/docusync/fixers/invalid_attributes.py

@@ -0,0 +1,50 @@
+"""Fixer for invalid HTML attributes."""
+
+import re
+from typing import Tuple
+
+from .base import Fixer
+
+
+class InvalidAttributesFixer(Fixer):
+    """Fix invalid HTML attributes for JSX.
+
+    Convert class -> className, for -> htmlFor, etc.
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the name of this fixer."""
+        return "HTML to JSX attributes"
+
+    def fix(self, content: str) -> Tuple[str, int]:
+        """Fix invalid HTML attributes.
+
+        :param content: The content to fix
+        :returns: Tuple of (fixed_content, number_of_fixes_applied)
+        """
+        fixes = 0
+
+        # class -> className
+        pattern = r"<(\w+)([^>]*?\s)class="
+        matches = re.findall(pattern, content)
+        if matches:
+            content = re.sub(
+                pattern,
+                r"<\1\2className=",
+                content,
+            )
+            fixes += len(matches)
+
+        # for -> htmlFor (in label tags)
+        pattern = r"<label([^>]*?\s)for="
+        matches = re.findall(pattern, content)
+        if matches:
+            content = re.sub(
+                pattern,
+                r"<label\1htmlFor=",
+                content,
+            )
+            fixes += len(matches)
+
+        return content, fixes

src/docusync/fixers/invalid_jsx_tags.py

@@ -0,0 +1,39 @@
+"""Fixer for invalid JSX tag names."""
+
+import re
+from typing import Tuple
+
+from .base import Fixer
+
+
+class InvalidJsxTagsFixer(Fixer):
+    """Fix JSX tags that start with numbers or invalid characters.
+
+    Example: <1something> -> &lt;1something&gt;
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the name of this fixer."""
+        return "Invalid JSX tag names"
+
+    def fix(self, content: str) -> Tuple[str, int]:
+        """Fix JSX tags that start with invalid characters.
+
+        :param content: The content to fix
+        :returns: Tuple of (fixed_content, number_of_fixes_applied)
+        """
+        # Match HTML/JSX tags that start with invalid characters
+        pattern = r"<(\d+[a-zA-Z_][\w-]*)"
+        matches = re.findall(pattern, content)
+
+        if matches:
+            # Escape these as HTML entities instead
+            for match in matches:
+                content = content.replace(f"<{match}", f"&lt;{match}").replace(
+                    f"</{match}>", f"&lt;/{match}&gt;"
+                )
+
+            return content, len(matches)
+
+        return content, 0

src/docusync/fixers/jsx_curly_braces.py

@@ -0,0 +1,97 @@
+"""Fixer for JSX curly braces."""
+
+import re
+from typing import Tuple
+
+from .base import Fixer
+
+
+class JsxCurlyBracesFixer(Fixer):
+    """Fix unescaped curly braces that might be interpreted as JSX.
+
+    Handles curly braces in two ways:
+    1. In inline code with single backticks: converts to double backticks
+    2. In text that looks like code (e.g., key:{value}): wraps in backticks
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the name of this fixer."""
+        return "Curly brace escaping"
+
+    def fix(self, content: str) -> Tuple[str, int]:
+        """Fix curly braces in inline code and code-like contexts.
+
+        :param content: The content to fix
+        :returns: Tuple of (fixed_content, number_of_fixes_applied)
+        """
+        in_code_block = False
+        lines = content.split("\n")
+        fixed_lines = []
+        fixes = 0
+
+        for line in lines:
+            # Track code blocks (``` blocks) - ignore any format like ```mermaid, ```python, etc.
+            if line.strip().startswith("```"):
+                in_code_block = not in_code_block
+                # Add code block delimiter without processing
+                fixed_lines.append(line)
+                continue
+
+            # Skip processing if we're inside a code block
+            # This ensures curly braces in code blocks (mermaid, python, etc.) are not modified
+            if not in_code_block:
+                original_line = line
+
+                # Step 1: Convert single backticks to double if content has braces
+                def convert_to_double_backticks(match: re.Match[str]) -> str:
+                    """Convert single backticks to double if content has braces."""
+                    code_content = match.group(1)
+                    if "{" in code_content or "}" in code_content:
+                        return f"``{code_content}``"
+                    return str(match.group(0))
+
+                pattern1 = r"(?<!`)`([^`\n]+)`(?!`)"
+                line = re.sub(pattern1, convert_to_double_backticks, line)
+
+                # Step 2: Wrap code-like patterns with curly braces in backticks
+                # Split line by existing backticks to process only text segments
+                def wrap_code_like_patterns(text: str) -> str:
+                    """Wrap code-like patterns with curly braces in backticks."""
+                    # Pattern 1: key:value:{variable} or key:{variable} (e.g., bot:health:{bot_id})
+                    # Match word:word:{word} or word:{word}
+                    text = re.sub(
+                        r"(?<!`)(\w+:\w+:\{[\w_]+\}|\w+:\{[\w_]+\})(?!`)",
+                        r"`\1`",
+                        text,
+                    )
+                    # Pattern 2: standalone {variable_name} that looks like code
+                    # Only if not already in backticks and not part of JSX expression
+                    text = re.sub(
+                        r"(?<!`)(?<!\w)\{[\w_]+\}(?!`)(?!\s*[:=])",
+                        r"`\0`",
+                        text,
+                    )
+                    return text
+
+                # Process text segments outside of backticks
+                parts = re.split(r"(`+[^`]*`+)", line)
+                processed_parts = []
+                for i, part in enumerate(parts):
+                    if part.startswith("`") and part.endswith("`"):
+                        # Already in backticks, keep as is
+                        processed_parts.append(part)
+                    else:
+                        # Process text segments
+                        processed_parts.append(wrap_code_like_patterns(part))
+
+                line = "".join(processed_parts)
+
+                if line != original_line:
+                    fixes += 1
+            # If in_code_block is True, line remains unchanged and is added as-is
+
+            # Add processed line (or original if inside code block)
+            fixed_lines.append(line)
+
+        return "\n".join(fixed_lines), fixes

src/docusync/fixers/numeric_entities.py

@@ -0,0 +1,33 @@
+"""Fixer for numeric HTML entities."""
+
+import re
+from typing import Tuple
+
+from .base import Fixer
+
+
+class NumericEntitiesFixer(Fixer):
+    """Fix numeric HTML entities that might cause issues.
+
+    Ensures numeric entities are properly formatted.
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the name of this fixer."""
+        return "Numeric entity formatting"
+
+    def fix(self, content: str) -> Tuple[str, int]:
+        """Fix malformed numeric entities.
+
+        :param content: The content to fix
+        :returns: Tuple of (fixed_content, number_of_fixes_applied)
+        """
+        # Fix malformed numeric entities
+        pattern = r"&#(?!x)(\d+)(?![;\d])"
+        matches = re.findall(pattern, content)
+        if matches:
+            content = re.sub(pattern, r"&#\1;", content)
+            return content, len(matches)
+
+        return content, 0