Bug: Aggressive '@' escaping in MarkdownHandler breaks PHPDoc annotations

[pigochu]

Bug: Aggressive '@' escaping in MarkdownHandler breaks PHPDoc annotations

Summary

The MarkdownHandler class in Jigsaw unconditionally escapes the @ symbol in all .md files by replacing it with {{'@'}}. While this feature is intended to help when writing documentation about Blade syntax, it has an unintended side effect of breaking common PHPDoc annotations (e.g., {@inheritDoc}) that are often present in PHP code examples within markdown files.

This leads to a Blade/PHP parsing error during the build process, making it difficult to include raw PHP code examples in documentation.

Steps to Reproduce

1. Create a standard Jigsaw project.

2. Create a markdown file (e.g., source/test.md) with a basic layout.

3. Add a PHP code block to the file that contains a PHPDoc annotation with an @ symbol. For example:

   ---
   extends: _layouts.master
   ---
   
   # Test Page with PHP code
   
   ```php
   /**
    * {@inheritDoc}
    */
   function test() {}

4. Run the Jigsaw build process (e.g., npm run production).

5. The build will fail with a ParseError: syntax error, unexpected token "{".

Expected Behavior

The build should complete successfully. The content {@inheritDoc} inside the code block should be treated as literal text and rendered correctly inside an HTML <pre><code>...</code></pre> block without being processed or modified by the Blade engine.

Actual Behavior

The build fails with a PHP parse error. The error originates from a Blade cache file, which contains invalid PHP generated during the compilation process.

Root Cause Analysis

The issue stems from the getEscapedMarkdownContent method in vendor/tightenco/jigsaw/src/Handlers/MarkdownHandler.php.

private function getEscapedMarkdownContent($file)
{
    // ...
    if (in_array($file->getFullExtension(), ['markdown', 'md', 'mdown'])) {
        $replacements = array_merge([
            '@' => "{{'@'}}", // This line is the problem
            '{{' => '@{{',
            '{!!' => '@{!!',
        ], $replacements);
    }
    return strtr($file->getContents(), $replacements);
}

This code unconditionally replaces every @ symbol. As a result, a string like {@inheritDoc} is transformed into {{{'@'}}inheritDoc}.

The Blade compiler then incorrectly parses this transformed string. It identifies {{ {'@'} }} as a Blade tag and inheritDoc} as a literal string. It compiles the tag into the following invalid PHP code, which is then followed by the literal string:

<?php echo e({'@'}); ?>inheritDoc}

The content of the tag, {'@'}, is not valid PHP syntax, which is what ultimately causes the ParseError: syntax error, unexpected token "{".