abdelrhmansaid / tempest-highlighter

🎨 Fast, extensible, server-side code highlighting for web and terminal

Fast, extensible, server-side code highlighting

You can read about why I started this package here.

• Quickstart
• Supported languages
• Themes
  • For the web
  • For the terminal
• Special highlighting tags
  • Emphasize strong and blur
  • Additions and deletions
  • Custom classes
  • Inline languages
• Commonmark integration
• Adding or extending languages

Quickstart

composer require tempest/highlight

Highlight code like this:

$highlighter = new \Tempest\Highlight\Highlighter();

$code = $highlighter->parse($code, 'php');

Supported languages

All supported languages can be found in the Languages folder. We welcome PRs with additional languages. You can read about creating your own languages here.

Themes

For the web

For HTML rendering, you can use one of the provided themes that comes with this package:

@import "../vendor/tempest/highlight/src/Themes/highlight-light-lite.css";
@import "../vendor/tempest/highlight/src/Themes/highlight-dark-lite.css";

You can build your own CSS theme with just a couple of classes, copy over the base stylesheet, and make adjustments however you like. Note that pre tag styling isn't included in this package.

For the terminal

use Tempest\Highlight\Highlighter;
use Tempest\Highlight\Themes\LightTerminalTheme;

$highlighter = new Highlighter(new LightTerminalTheme());

echo $highlighter->parse($code, 'php');

Special highlighting tags

This package offers a collection of special tags that you can use within your code snippets. These tags won't be shown in the final output, but rather adjust the highlighter's default styling. All these tags work multi-line, and will still properly render its wrapped content.

Emphasize, strong, and blur

You can add these tags within your code to emphasize or blur parts:

• {_ content _} adds the .hl-em class
• {* content *} adds the .hl-strong class
• {~ content ~} adds the .hl-blur class

Here's an example:

{~public function parse(string $content, Highlighter $highlighter): string
{
    $pattern = '/\{\~(?<match>(.|\n)*)\~\}/';
    
    preg_match($pattern, $content, $matches);

    if ($matches === []) {
        return $content;
    }~} // This part is blurred

    {*$content = preg_replace_callback(*} // This line is bold
        $pattern,
        function (array $matches) use ($highlighter) {
            $parsed = $highlighter->parse($matches['match'], $highlighter->getCurrentLanguage());
            
            return '<span class="hl-blur">' . $parsed . '</span>';
        },
        {_$content_} // This line is cursive
    );
    
    {~return $highlighter->parse($content, $highlighter->getCurrentLanguage());
}~}

This is the end result:

Additions and deletions

You can use these two tags to mark lines as additions and deletions:

• {+ content +} adds the .hl-addition class
• {- content -} adds the .hl-deletion class

{-public class Foo {}-}
{+public class Bar {}+}

As a reminder: all these tags work multi-line as well:

  public function before(TokenType $tokenType): string
  {
      $style = match ($tokenType) {
          {-TokenType::KEYWORD => TerminalStyle::FG_DARK_BLUE,
          TokenType::PROPERTY => TerminalStyle::FG_DARK_GREEN,
          TokenType::TYPE => TerminalStyle::FG_DARK_RED,
          TokenType::GENERIC => TerminalStyle::FG_DARK_CYAN,
          TokenType::VALUE => TerminalStyle::FG_BLACK,
          TokenType::COMMENT => TerminalStyle::FG_GRAY,
          TokenType::ATTRIBUTE => TerminalStyle::RESET,-}
      };
  
      return TerminalStyle::ESC->value . $style->value;
  }

Custom classes

You can add any class you'd like by using the {:classname: content :} tag:

<style>
.hl-a {
    background-color: #FFFF0077;
}

.hl-b {
    background-color: #FF00FF33;
}
</style>

```php
{:hl-a:public class Foo {}:}
{:hl-b:public class Bar {}:}
```

Inline languages

Within inline Markdown code tags, you can specify the language by prepending it between curly brackets:

`{php}public function before(TokenType $tokenType): string`

You'll need to set up commonmark properly to get this to work.

CommonMark integration

If you're using league/commonmark, you can highlight codeblocks and inline code like so:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
use League\CommonMark\MarkdownConverter;
use Tempest\Highlight\CommonMark\CodeBlockRenderer;
use Tempest\Highlight\CommonMark\InlineCodeBlockRenderer;

$environment = new Environment();

$environment
    ->addExtension(new CommonMarkCoreExtension())
    ->addRenderer(FencedCode::class, new CodeBlockRenderer())
    ->addRenderer(Code::class, new InlineCodeBlockRenderer())
    ;

$markdown = new MarkdownConverter($environment);

Keep in mind that you need to manually install league/commonmark:

composer require league/commonmark;

Adding or extending languages

This package makes it easy for developers to add new languages or extend existing languages.

In order to build your own highlighter functionality, you need to understand three concepts of how code is highlighted: patterns, injections, and languages. Continue reading.

You can also watch this video to get a better understand of the package's architecture: