Getting Started

tempest/highlight is a package for server-side, high-performance, and flexible code highlighting. Give it a ⭐️ on GitHub!

Quickstart#

Require tempest/highlight with composer:

composer require tempest/highlight

And highlight code like this:

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

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

Supported languages#

All supported languages can be found in the GitHub repository.

Themes#

There are a bunch of themes included in this package. You can load them either by importing the correct CSS file into your project's CSS file, or you can manually copy a stylesheet.

@import "../../../../../vendor/tempest/highlight/src/Themes/Css/highlight-light-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.

Inline themes#

If you don't want to or can't load a CSS file, you can opt to use the InlineTheme class. This theme takes the path to a CSS file, and will parse it into inline styles:

$highlighter = (new Highlighter(new InlineTheme(__DIR__ . '/../src/Themes/Css/solarized-dark.css')));

Terminal themes#

Terminal themes are simpler because of their limited styling options. Right now there's one terminal theme provided: LightTerminalTheme. More terminal themes are planned to be added in the future.

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

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

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

Gutter#

This package can render an optional gutter if needed.

$highlighter = (new Highlighter())->withGutter(startAt: 10);

The gutter will show additions and deletions, and can start at any given line number:

  10  public function before(TokenType $tokenType): string
  11  {
  12      $style = match ($tokenType) {
13 -          TokenType::KEYWORD => TerminalStyle::FG_DARK_BLUE,
14 -          TokenType::PROPERTY => TerminalStyle::FG_DARK_GREEN,
15 -          TokenType::TYPE => TerminalStyle::FG_DARK_RED,
16 +          TokenType::GENERIC => TerminalStyle::FG_DARK_CYAN,
  17          TokenType::VALUE => TerminalStyle::FG_BLACK,
  18          TokenType::COMMENT => TerminalStyle::FG_GRAY,
  19          TokenType::ATTRIBUTE => TerminalStyle::RESET,
  20      };
  21  
  22      return TerminalStyle::ESC->value . $style->value;
  23  }

Finally, you can enable gutter rendering on the fly if you're using commonmark code blocks by appending {startAt} to the language definition:

```php{10}
echo 'hi'!
```

10echo 'hi'!

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.

Note that highlight tags are not supported in terminal themes.

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

{_Emphasized text_}
{*Strong text*}
{~Blurred text~}

This is the end result:

{_Emphasized text_}
{*Strong text*}
{~Blurred text~}

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 {}+}

public class Foo {}
public class Bar {}

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

   1  public function before(TokenType $tokenType): string
   2  {
   3      $style = match ($tokenType) {
 4 -          TokenType::KEYWORD => TerminalStyle::FG_DARK_BLUE,
 5 -          TokenType::PROPERTY => TerminalStyle::FG_DARK_GREEN,
 6 -          TokenType::TYPE => TerminalStyle::FG_DARK_RED,
 7 -          TokenType::GENERIC => TerminalStyle::FG_DARK_CYAN,
 8 -          TokenType::VALUE => TerminalStyle::FG_BLACK,
 9 -          TokenType::COMMENT => TerminalStyle::FG_GRAY,
10 -          TokenType::ATTRIBUTE => TerminalStyle::RESET,
  11      };
  12  
  13      return TerminalStyle::ESC->value . $style->value;
  14  }

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 {}:}
```

public class Foo {}
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\MarkdownConverter;
use Tempest\Highlight\CommonMark\HighlightExtension;

$environment = new Environment();

$environment
    ->addExtension(new CommonMarkCoreExtension())
    ->addExtension(new HighlightExtension());

$markdown = new MarkdownConverter($environment);

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

composer require league/commonmark;