PHPackages                             torchlight/engine - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. torchlight/engine

ActiveLibrary[Utility & Helpers](/categories/utility)

torchlight/engine
=================

The PHP-based Torchlight code annotation and rendering engine.

v1.0.0(2mo ago)655.7k↓46.3%[2 issues](https://github.com/torchlight-api/engine/issues)2MITPHPPHP ^8.2CI passing

Since Apr 2Pushed 1y ago2 watchersCompare

[ Source](https://github.com/torchlight-api/engine)[ Packagist](https://packagist.org/packages/torchlight/engine)[ RSS](/packages/torchlight-engine/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (10)Versions (5)Used By (2)

  ![Torchlight Engine](./.art/banner.png)Torchlight Engine brings Torchlight's code annotation syntax to PHP, built on top of the excellent [Phiki](https://github.com/phikiphp/phiki) syntax highlighting package. **No node or API required**.

Torchlight enables you to add annotations to your code, drawing your reader's attention to specific parts, highlighting lines, visualizing diffs, and much more. Combined with the syntax highlighting provided by Phiki, Torchlight is a perfect fit for technical blogs, documentation, and so much more.

Torchlight annotations are written as comments in the language of your code sample, eliminating red squigglies and errors within your editor or IDE.

As an example, here is how we could focus our reader's attention on lines 6 and 7:

```
return [
    'extensions' => [
        // Add attributes straight from markdown.
        AttributesExtension::class,

        // Add Torchlight syntax highlighting. [tl! focus]
        TorchlightExtension::class, // [tl! focus]
    ]
]
```

When rendered, our readers would be presented with something like the following:

[![Focus Annotation Example](./.art/readme/example_intro_focus.png)](./.art/readme/example_intro_focus.png)

How simple is that? We're pretty proud of it and know you'll love it, too.

- [Installation](#installation)
- [Getting Started](#getting-started)
    - [Modifying the CommonMark Extension](#modifying-the-commonmark-extension)
        - [Specifying the Extension's Default Language](#specifying-the-extensions-default-language)
        - [Caching Highlighted Code](#caching-highlighted-code)
    - [Laravel](#laravel)
    - [Statamic](#statamic)
    - [Rendering Code Manually](#rendering-code-manually)
    - [Notes on User Provided Content](#notes-on-user-provided-content)
- [Frequently Asked Questions](#frequently-asked-questions)
    - [Is the Torchlight API going away now?](#is-the-torchlight-api-going-away-now)
    - [How much does Torchlight Engine cost?](#how-much-does-torchlight-engine-cost)
    - [Does Torchlight Engine require an API key or network access?](#does-torchlight-engine-require-an-api-key-or-network-access)
    - [What about the Laravel and CommonMark packages?](#what-about-the-laravel-and-commonmark-packages)
    - [Will this package replace the existing CommonMark package?](#will-this-package-replace-the-existing-commonmark-package)
    - [Some themes are missing compared to the API version. How come?](#some-themes-are-missing-compared-to-the-api-version-how-come)
    - [Can I add custom themes to Torchlight Engine?](#can-i-add-custom-themes-to-torchlight-engine)
    - [Are the custom grammars from the API version supported?](#are-the-custom-grammars-from-the-api-version-supported)
    - [Some of my highlighting looks different now. How come?](#some-of-my-highlighting-looks-different-now-how-come)
    - [Are there breaking changes?](#are-there-breaking-changes)
- [Differences Between Torchlight Engine and Torchlight API](#differences-between-torchlight-engine-and-torchlight-api)
- [CSS and Theming](#css-and-theming)
    - [Standard CSS](#standard-css)
    - [Tailwind](#tailwind)
    - [Dark Mode](#dark-mode)
    - [Available Themes](#available-themes)
- [Annotations](#annotations)
    - [Plain Text Annotations](#plain-text-annotations)
    - [JSON Annotations](#json-annotations)
    - [Ranges](#ranges)
        - [Annotation Range Cheat Sheet](#annotation-range-cheat-sheet)
        - [Single Lines](#single-lines)
        - [N-Many Lines](#n-many-lines)
        - [Offset and Length](#offset-and-length)
        - [Applying an Annotation to All Lines](#applying-an-annotation-to-all-lines)
        - [Start and End](#start-and-end)
        - [Supported Annotations](#supported-annotations)
    - [Highlighting Lines](#highlighting-lines)
        - [Alternative Highlight Class](#alternative-highlight-class)
        - [Highlight Shorthand](#highlight-shorthand)
    - [Focusing](#focusing)
        - [Focusing Shorthand](#focusing-shorthand)
        - [Focusing CSS](#focusing-css)
    - [Collapsing](#collapsing)
        - [Customizing the Summary Text](#customizing-the-summary-text)
        - [Collapsing Required CSS](#collapsing-required-css)
        - [Default to Open](#default-to-open)
        - [Removing Summary Carets](#removing-summary-carets)
    - [Diffs](#diffs)
        - [Diff Shorthand](#diff-shorthand)
        - [Removing Diff Indicators](#removing-diff-indicators)
        - [Standalone Diff Indicators](#standalone-diff-indicators)
        - [Diff Indicators Without Line Numbers](#diff-indicators-without-line-numbers)
        - [Diff Ranges](#diff-ranges)
        - [Preserving Syntax Colors](#preserving-syntax-colors)
    - [Classes and IDs](#classes-and-ids)
        - [Using Range Modifiers](#using-range-modifiers)
        - [Character Ranges](#character-ranges)
    - [Auto-linking URLs](#auto-linking-urls)
        - [Link Requirements](#link-requirements)
        - [Link Ranges](#link-ranges)
    - [Reindexing Line Numbers](#reindexing-line-numbers)
        - [Manually Setting a New Number](#manually-setting-a-new-number)
        - [No Line Number at All](#no-line-number-at-all)
        - [Relative Line Number Changes](#relative-line-number-changes)
        - [Reindexing with Range Modifiers](#reindexing-with-range-modifiers)
        - [Reindex Differences Between Torchlight API](#reindex-differences-between-torchlight-api)
        - [Vim-style Relative Line Numbers](#vim-style-relative-line-numbers)
- [Highlighting Files and Directory Structures](#highlighting-files-and-directory-structures)
- [Options](#options)
    - [Setting Default Options Globally](#setting-default-options-globally)
    - [Setting Default Themes Globally](#setting-default-themes-globally)
    - [Setting Options Per Block](#setting-options-per-block)
    - [Line Numbers](#line-numbers)
        - [Changing the Starting Line Number](#changing-the-starting-line-number)
        - [Changing Line Number Styles](#changing-line-number-styles)
        - [Adding Line Number Right Padding](#adding-line-number-right-padding)
    - [Summary Indicator](#summary-indicator)
    - [Adding Extra Classes to the Torchlight Code Element](#adding-extra-classes-to-the-torchlight-code-element)
    - [The Copyable Option](#the-copyable-option)
    - [Disabling Torchlight Annotations](#disabling-torchlight-annotations)
- [Reporting Issues](#reporting-issues)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

Installation
------------

[](#installation)

You may install Torchlight Engine via Composer:

```
composer require torchlight/engine
```

Torchlight Engine requires at least PHP 8.2, but PHP 8.4+ is recommended.

Getting Started
---------------

[](#getting-started)

Torchlight Engine provides a `league/commonmark` extension, making it simple to start using Torchlight in your markdown content.

You may register the extension with any CommonMark `Environment` object like so:

```