perf: add caching layer for frequently accessed operations

Add instance and result caching for hot paths in the rendering pipeline:

- ProjectNode: cache root document entry with O(1) lookup, add fast-path
  to getDocumentEntry(), lazy cache invalidation in setDocumentEntries()
- DocumentNode: add hasDocumentEntry() helper for safe checks
- RenderContext: use hash map for O(1) document lookup by file path,
  optimize withDocument() to clone directly instead of rebuilding
- DocumentNameResolver: cache URI analysis and resolved paths
- ExternalReferenceResolver: pre-compile schema regex pattern
- SluggerAnchorNormalizer: cache slugger instance and normalization results
- AbstractUrlGenerator: cache isRelativePath() checks
- RelativeUrlGenerator: cache computed relative paths
- PreNodeRendererFactory: cache renderer lookups by node class
- TwigEnvironmentBuilder: enable filesystem template caching
- TwigTemplateRenderer: cache global context to avoid redundant addGlobal()

See https://cybottm.github.io/render-guides/ for benchmark data.

Author: CybotTM

packages/guides/src/NodeRenderers/PreRenderers/PreNodeRendererFactory.php

@@ -21,9 +21,16 @@
 
 /**
  * Decorator to add pre-rendering logic to node renderers.
+ *
+ * Note: Caching assumes PreNodeRenderer::supports() only checks the node's
+ * class type, not instance-specific properties. If a PreNodeRenderer needs
+ * to check node properties, caching by class would return incorrect results.
  */
 final class PreNodeRendererFactory implements NodeRendererFactory
 {
+    /** @var array<class-string<Node>, NodeRenderer<Node>> */
+    private array $cache = [];
+
     public function __construct(
         private readonly NodeRendererFactory $innerFactory,
         /** @var iterable<PreNodeRenderer> */
@@ -33,6 +40,12 @@ public function __construct(
 
     public function get(Node $node): NodeRenderer
     {
+        // Cache by node class to avoid repeated preRenderer iteration
+        $nodeFqcn = $node::class;
+        if (isset($this->cache[$nodeFqcn])) {
+            return $this->cache[$nodeFqcn];
+        }
+
         $preRenderers = [];
         foreach ($this->preRenderers as $preRenderer) {
             if (!$preRenderer->supports($node)) {
@@ -43,9 +56,9 @@ public function get(Node $node): NodeRenderer
         }
 
         if (count($preRenderers) === 0) {
-            return $this->innerFactory->get($node);
+            return $this->cache[$nodeFqcn] = $this->innerFactory->get($node);
         }
 
-        return new PreRenderer($this->innerFactory->get($node), $preRenderers);
+        return $this->cache[$nodeFqcn] = new PreRenderer($this->innerFactory->get($node), $preRenderers);
     }
 }

packages/guides/src/Nodes/DocumentNode.php

@@ -279,6 +279,11 @@ public function getFootnoteTargetAnonymous(): FootnoteTarget|null
         return null;
     }
 
+    public function hasDocumentEntry(): bool
+    {
+        return $this->documentEntry !== null;
+    }
+
     public function getDocumentEntry(): DocumentEntryNode
     {
         if ($this->documentEntry === null) {

packages/guides/src/ReferenceResolvers/DocumentNameResolver.php

@@ -23,6 +23,18 @@
 
 final class DocumentNameResolver implements DocumentNameResolverInterface
 {
+    /** @var array<string, string> */
+    private array $absoluteUrlCache = [];
+
+    /** @var array<string, string> */
+    private array $canonicalUrlCache = [];
+
+    /** @var array<string, bool> */
+    private array $isAbsoluteCache = [];
+
+    /** @var array<string, bool> */
+    private array $isAbsolutePathCache = [];
+
     /**
      * Returns the absolute path, including prefixing '/'.
      *
@@ -31,20 +43,31 @@ final class DocumentNameResolver implements DocumentNameResolverInterface
      */
     public function absoluteUrl(string $basePath, string $url): string
     {
-        $uri = BaseUri::from($url);
-        if ($uri->isAbsolute()) {
-            return $url;
+        $cacheKey = $basePath . '|' . $url;
+        if (isset($this->absoluteUrlCache[$cacheKey])) {
+            return $this->absoluteUrlCache[$cacheKey];
+        }
+
+        // Cache URI analysis results separately by URL
+        if (!isset($this->isAbsoluteCache[$url])) {
+            $uri = BaseUri::from($url);
+            $this->isAbsoluteCache[$url] = $uri->isAbsolute();
+            $this->isAbsolutePathCache[$url] = $uri->isAbsolutePath();
+        }
+
+        if ($this->isAbsoluteCache[$url]) {
+            return $this->absoluteUrlCache[$cacheKey] = $url;
         }
 
-        if ($uri->isAbsolutePath()) {
-            return $url;
+        if ($this->isAbsolutePathCache[$url]) {
+            return $this->absoluteUrlCache[$cacheKey] = $url;
         }
 
         if ($basePath === '/') {
-            return $basePath . $url;
+            return $this->absoluteUrlCache[$cacheKey] = $basePath . $url;
         }
 
-        return '/' . trim($basePath, '/') . '/' . $url;
+        return $this->absoluteUrlCache[$cacheKey] = '/' . trim($basePath, '/') . '/' . $url;
     }
 
     /**
@@ -57,8 +80,13 @@ public function absoluteUrl(string $basePath, string $url): string
      */
     public function canonicalUrl(string $basePath, string $url): string
     {
+        $cacheKey = $basePath . '|' . $url;
+        if (isset($this->canonicalUrlCache[$cacheKey])) {
+            return $this->canonicalUrlCache[$cacheKey];
+        }
+
         if ($url[0] === '/') {
-            return ltrim($url, '/');
+            return $this->canonicalUrlCache[$cacheKey] = ltrim($url, '/');
         }
 
         $dirNameParts = explode('/', $basePath);
@@ -78,6 +106,6 @@ public function canonicalUrl(string $basePath, string $url): string
             $urlPass1[] = $part;
         }
 
-        return ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
+        return $this->canonicalUrlCache[$cacheKey] = ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
     }
 }

packages/guides/src/ReferenceResolvers/ExternalReferenceResolver.php

@@ -16,9 +16,9 @@
 use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
 use phpDocumentor\Guides\RenderContext;
 
+use function array_fill_keys;
 use function filter_var;
 use function parse_url;
-use function preg_match;
 use function str_starts_with;
 
 use const FILTER_VALIDATE_EMAIL;
@@ -35,7 +35,67 @@
 final class ExternalReferenceResolver implements ReferenceResolver
 {
     public final const PRIORITY = -100;
-    final public const SUPPORTED_SCHEMAS = '(?:aaa|aaas|about|acap|acct|acd|acr|adiumxtra|adt|afp|afs|aim|amss|android|appdata|apt|ar|ark|at|attachment|aw|barion|bb|beshare|bitcoin|bitcoincash|blob|bolo|browserext|cabal|calculator|callto|cap|cast|casts|chrome|chrome-extension|cid|coap|coap+tcp|coap+ws|coaps|coaps+tcp|coaps+ws|com-eventbrite-attendee|content|content-type|crid|cstr|cvs|dab|dat|data|dav|dhttp|diaspora|dict|did|dis|dlna-playcontainer|dlna-playsingle|dns|dntp|doi|dpp|drm|drop|dtmi|dtn|dvb|dvx|dweb|ed2k|eid|elsi|embedded|ens|ethereum|example|facetime|fax|feed|feedready|fido|file|filesystem|finger|first-run-pen-experience|fish|fm|ftp|fuchsia-pkg|geo|gg|git|gitoid|gizmoproject|go|gopher|graph|grd|gtalk|h323|ham|hcap|hcp|http|https|hxxp|hxxps|hydrazone|hyper|iax|icap|icon|im|imap|info|iotdisco|ipfs|ipn|ipns|ipp|ipps|irc|irc6|ircs|iris|iris\.beep|iris\.lwz|iris\.xpc|iris\.xpcs|isostore|itms|jabber|jar|jms|keyparc|lastfm|lbry|ldap|ldaps|leaptofrogans|lorawan|lpa|lvlt|magnet|mailserver|mailto|maps|market|matrix|message|microsoft\.windows\.camera|microsoft\.windows\.camera\.multipicker|microsoft\.windows\.camera\.picker|mid|mms|modem|mongodb|moz|ms-access|ms-appinstaller|ms-browser-extension|ms-calculator|ms-drive-to|ms-enrollment|ms-excel|ms-eyecontrolspeech|ms-gamebarservices|ms-gamingoverlay|ms-getoffice|ms-help|ms-infopath|ms-inputapp|ms-launchremotedesktop|ms-lockscreencomponent-config|ms-media-stream-id|ms-meetnow|ms-mixedrealitycapture|ms-mobileplans|ms-newsandinterests|ms-officeapp|ms-people|ms-project|ms-powerpoint|ms-publisher|ms-remotedesktop|ms-remotedesktop-launch|ms-restoretabcompanion|ms-screenclip|ms-screensketch|ms-search|ms-search-repair|ms-secondary-screen-controller|ms-secondary-screen-setup|ms-settings|ms-settings-airplanemode|ms-settings-bluetooth|ms-settings-camera|ms-settings-cellular|ms-settings-cloudstorage|ms-settings-connectabledevices|ms-settings-displays-topology|ms-settings-emailandaccounts|ms-settings-language|ms-settings-location|ms-settings-lock|ms-settings-nfctransactions|ms-settings-notifications|ms-settings-power|ms-settings-privacy|ms-settings-proximity|ms-settings-screenrotation|ms-settings-wifi|ms-settings-workplace|ms-spd|ms-stickers|ms-sttoverlay|ms-transit-to|ms-useractivityset|ms-virtualtouchpad|ms-visio|ms-walk-to|ms-whiteboard|ms-whiteboard-cmd|ms-word|msnim|msrp|msrps|mss|mt|mtqp|mumble|mupdate|mvn|news|nfs|ni|nih|nntp|notes|num|ocf|oid|onenote|onenote-cmd|opaquelocktoken|openpgp4fpr|otpauth|p1|pack|palm|paparazzi|payment|payto|pkcs11|platform|pop|pres|prospero|proxy|pwid|psyc|pttp|qb|query|quic-transport|redis|rediss|reload|res|resource|rmi|rsync|rtmfp|rtmp|rtsp|rtsps|rtspu|sarif|secondlife|secret-token|service|session|sftp|sgn|shc|shttp (OBSOLETE)|sieve|simpleledger|simplex|sip|sips|skype|smb|smp|sms|smtp|snews|snmp|soap\.beep|soap\.beeps|soldat|spiffe|spotify|ssb|ssh|starknet|steam|stun|stuns|submit|svn|swh|swid|swidpath|tag|taler|teamspeak|tel|teliaeid|telnet|tftp|things|thismessage|tip|tn3270|tool|turn|turns|tv|udp|unreal|upt|urn|ut2004|uuid-in-package|v-event|vemmi|ventrilo|ves|videotex|vnc|view-source|vscode|vscode-insiders|vsls|w3|wais|web3|wcr|webcal|web+ap|wifi|wpid|ws|wss|wtai|wyciwyg|xcon|xcon-userid|xfire|xmlrpc\.beep|xmlrpc\.beeps|xmpp|xri|ymsgr|z39\.50|z39\.50r|z39\.50s)';
+
+    /**
+     * Regex alternation pattern of supported URI schemes.
+     *
+     * @deprecated Use isSupportedScheme() for O(1) lookup instead of regex matching.
+     * @see https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
+     */
+    final public const SUPPORTED_SCHEMAS = '(?:aaa|aaas|about|acap|acct|acd|acr|adiumxtra|adt|afp|afs|aim|amss|android|appdata|apt|ar|ark|at|attachment|aw|barion|bb|beshare|bitcoin|bitcoincash|blob|bolo|browserext|cabal|calculator|callto|cap|cast|casts|chrome|chrome-extension|cid|coap|coap\+tcp|coap\+ws|coaps|coaps\+tcp|coaps\+ws|com-eventbrite-attendee|content|content-type|crid|cstr|cvs|dab|dat|data|dav|dhttp|diaspora|dict|did|dis|dlna-playcontainer|dlna-playsingle|dns|dntp|doi|dpp|drm|drop|dtmi|dtn|dvb|dvx|dweb|ed2k|eid|elsi|embedded|ens|ethereum|example|facetime|fax|feed|feedready|fido|file|filesystem|finger|first-run-pen-experience|fish|fm|ftp|fuchsia-pkg|geo|gg|git|gitoid|gizmoproject|go|gopher|graph|grd|gtalk|h323|ham|hcap|hcp|http|https|hxxp|hxxps|hydrazone|hyper|iax|icap|icon|im|imap|info|iotdisco|ipfs|ipn|ipns|ipp|ipps|irc|irc6|ircs|iris|iris\.beep|iris\.lwz|iris\.xpc|iris\.xpcs|isostore|itms|jabber|jar|jms|keyparc|lastfm|lbry|ldap|ldaps|leaptofrogans|lorawan|lpa|lvlt|magnet|mailserver|mailto|maps|market|matrix|message|microsoft\.windows\.camera|microsoft\.windows\.camera\.multipicker|microsoft\.windows\.camera\.picker|mid|mms|modem|mongodb|moz|ms-access|ms-appinstaller|ms-browser-extension|ms-calculator|ms-drive-to|ms-enrollment|ms-excel|ms-eyecontrolspeech|ms-gamebarservices|ms-gamingoverlay|ms-getoffice|ms-help|ms-infopath|ms-inputapp|ms-launchremotedesktop|ms-lockscreencomponent-config|ms-media-stream-id|ms-meetnow|ms-mixedrealitycapture|ms-mobileplans|ms-newsandinterests|ms-officeapp|ms-people|ms-project|ms-powerpoint|ms-publisher|ms-remotedesktop|ms-remotedesktop-launch|ms-restoretabcompanion|ms-screenclip|ms-screensketch|ms-search|ms-search-repair|ms-secondary-screen-controller|ms-secondary-screen-setup|ms-settings|ms-settings-airplanemode|ms-settings-bluetooth|ms-settings-camera|ms-settings-cellular|ms-settings-cloudstorage|ms-settings-connectabledevices|ms-settings-displays-topology|ms-settings-emailandaccounts|ms-settings-language|ms-settings-location|ms-settings-lock|ms-settings-nfctransactions|ms-settings-notifications|ms-settings-power|ms-settings-privacy|ms-settings-proximity|ms-settings-screenrotation|ms-settings-wifi|ms-settings-workplace|ms-spd|ms-stickers|ms-sttoverlay|ms-transit-to|ms-useractivityset|ms-virtualtouchpad|ms-visio|ms-walk-to|ms-whiteboard|ms-whiteboard-cmd|ms-word|msnim|msrp|msrps|mss|mt|mtqp|mumble|mupdate|mvn|news|nfs|ni|nih|nntp|notes|num|ocf|oid|onenote|onenote-cmd|opaquelocktoken|openpgp4fpr|otpauth|p1|pack|palm|paparazzi|payment|payto|pkcs11|platform|pop|pres|prospero|proxy|pwid|psyc|pttp|qb|query|quic-transport|redis|rediss|reload|res|resource|rmi|rsync|rtmfp|rtmp|rtsp|rtsps|rtspu|sarif|secondlife|secret-token|service|session|sftp|sgn|shc|shttp \(OBSOLETE\)|sieve|simpleledger|simplex|sip|sips|skype|smb|smp|sms|smtp|snews|snmp|soap\.beep|soap\.beeps|soldat|spiffe|spotify|ssb|ssh|starknet|steam|stun|stuns|submit|svn|swh|swid|swidpath|tag|taler|teamspeak|tel|teliaeid|telnet|tftp|things|thismessage|tip|tn3270|tool|turn|turns|tv|udp|unreal|upt|urn|ut2004|uuid-in-package|v-event|vemmi|ventrilo|ves|videotex|vnc|view-source|vscode|vscode-insiders|vsls|w3|wais|web3|wcr|webcal|web\+ap|wifi|wpid|ws|wss|wtai|wyciwyg|xcon|xcon-userid|xfire|xmlrpc\.beep|xmlrpc\.beeps|xmpp|xri|ymsgr|z39\.50|z39\.50r|z39\.50s)';
+
+    /**
+     * List of supported URI schemes for O(1) lookup.
+     *
+     * @var list<string>
+     */
+    private const SUPPORTED_SCHEMAS_LIST = [
+        'aaa', 'aaas', 'about', 'acap', 'acct', 'acd', 'acr', 'adiumxtra', 'adt', 'afp', 'afs', 'aim', 'amss',
+        'android', 'appdata', 'apt', 'ar', 'ark', 'at', 'attachment', 'aw', 'barion', 'bb', 'beshare', 'bitcoin',
+        'bitcoincash', 'blob', 'bolo', 'browserext', 'cabal', 'calculator', 'callto', 'cap', 'cast', 'casts',
+        'chrome', 'chrome-extension', 'cid', 'coap', 'coap+tcp', 'coap+ws', 'coaps', 'coaps+tcp', 'coaps+ws',
+        'com-eventbrite-attendee', 'content', 'content-type', 'crid', 'cstr', 'cvs', 'dab', 'dat', 'data', 'dav',
+        'dhttp', 'diaspora', 'dict', 'did', 'dis', 'dlna-playcontainer', 'dlna-playsingle', 'dns', 'dntp', 'doi',
+        'dpp', 'drm', 'drop', 'dtmi', 'dtn', 'dvb', 'dvx', 'dweb', 'ed2k', 'eid', 'elsi', 'embedded', 'ens',
+        'ethereum', 'example', 'facetime', 'fax', 'feed', 'feedready', 'fido', 'file', 'filesystem', 'finger',
+        'first-run-pen-experience', 'fish', 'fm', 'ftp', 'fuchsia-pkg', 'geo', 'gg', 'git', 'gitoid', 'gizmoproject',
+        'go', 'gopher', 'graph', 'grd', 'gtalk', 'h323', 'ham', 'hcap', 'hcp', 'http', 'https', 'hxxp', 'hxxps',
+        'hydrazone', 'hyper', 'iax', 'icap', 'icon', 'im', 'imap', 'info', 'iotdisco', 'ipfs', 'ipn', 'ipns',
+        'ipp', 'ipps', 'irc', 'irc6', 'ircs', 'iris', 'iris.beep', 'iris.lwz', 'iris.xpc', 'iris.xpcs', 'isostore',
+        'itms', 'jabber', 'jar', 'jms', 'keyparc', 'lastfm', 'lbry', 'ldap', 'ldaps', 'leaptofrogans', 'lorawan',
+        'lpa', 'lvlt', 'magnet', 'mailserver', 'mailto', 'maps', 'market', 'matrix', 'message',
+        'microsoft.windows.camera', 'microsoft.windows.camera.multipicker', 'microsoft.windows.camera.picker',
+        'mid', 'mms', 'modem', 'mongodb', 'moz', 'ms-access', 'ms-appinstaller', 'ms-browser-extension',
+        'ms-calculator', 'ms-drive-to', 'ms-enrollment', 'ms-excel', 'ms-eyecontrolspeech', 'ms-gamebarservices',
+        'ms-gamingoverlay', 'ms-getoffice', 'ms-help', 'ms-infopath', 'ms-inputapp', 'ms-launchremotedesktop',
+        'ms-lockscreencomponent-config', 'ms-media-stream-id', 'ms-meetnow', 'ms-mixedrealitycapture',
+        'ms-mobileplans', 'ms-newsandinterests', 'ms-officeapp', 'ms-people', 'ms-project', 'ms-powerpoint',
+        'ms-publisher', 'ms-remotedesktop', 'ms-remotedesktop-launch', 'ms-restoretabcompanion', 'ms-screenclip',
+        'ms-screensketch', 'ms-search', 'ms-search-repair', 'ms-secondary-screen-controller',
+        'ms-secondary-screen-setup', 'ms-settings', 'ms-settings-airplanemode', 'ms-settings-bluetooth',
+        'ms-settings-camera', 'ms-settings-cellular', 'ms-settings-cloudstorage', 'ms-settings-connectabledevices',
+        'ms-settings-displays-topology', 'ms-settings-emailandaccounts', 'ms-settings-language',
+        'ms-settings-location', 'ms-settings-lock', 'ms-settings-nfctransactions', 'ms-settings-notifications',
+        'ms-settings-power', 'ms-settings-privacy', 'ms-settings-proximity', 'ms-settings-screenrotation',
+        'ms-settings-wifi', 'ms-settings-workplace', 'ms-spd', 'ms-stickers', 'ms-sttoverlay', 'ms-transit-to',
+        'ms-useractivityset', 'ms-virtualtouchpad', 'ms-visio', 'ms-walk-to', 'ms-whiteboard', 'ms-whiteboard-cmd',
+        'ms-word', 'msnim', 'msrp', 'msrps', 'mss', 'mt', 'mtqp', 'mumble', 'mupdate', 'mvn', 'news', 'nfs', 'ni',
+        'nih', 'nntp', 'notes', 'num', 'ocf', 'oid', 'onenote', 'onenote-cmd', 'opaquelocktoken', 'openpgp4fpr',
+        'otpauth', 'p1', 'pack', 'palm', 'paparazzi', 'payment', 'payto', 'pkcs11', 'platform', 'pop', 'pres',
+        'prospero', 'proxy', 'pwid', 'psyc', 'pttp', 'qb', 'query', 'quic-transport', 'redis', 'rediss', 'reload',
+        'res', 'resource', 'rmi', 'rsync', 'rtmfp', 'rtmp', 'rtsp', 'rtsps', 'rtspu', 'sarif', 'secondlife',
+        'secret-token', 'service', 'session', 'sftp', 'sgn', 'shc', 'shttp (OBSOLETE)', 'sieve', 'simpleledger',
+        'simplex', 'sip', 'sips', 'skype', 'smb', 'smp', 'sms', 'smtp', 'snews', 'snmp', 'soap.beep', 'soap.beeps',
+        'soldat', 'spiffe', 'spotify', 'ssb', 'ssh', 'starknet', 'steam', 'stun', 'stuns', 'submit', 'svn', 'swh',
+        'swid', 'swidpath', 'tag', 'taler', 'teamspeak', 'tel', 'teliaeid', 'telnet', 'tftp', 'things', 'thismessage',
+        'tip', 'tn3270', 'tool', 'turn', 'turns', 'tv', 'udp', 'unreal', 'upt', 'urn', 'ut2004', 'uuid-in-package',
+        'v-event', 'vemmi', 'ventrilo', 'ves', 'videotex', 'vnc', 'view-source', 'vscode', 'vscode-insiders', 'vsls',
+        'w3', 'wais', 'web3', 'wcr', 'webcal', 'web+ap', 'wifi', 'wpid', 'ws', 'wss', 'wtai', 'wyciwyg', 'xcon',
+        'xcon-userid', 'xfire', 'xmlrpc.beep', 'xmlrpc.beeps', 'xmpp', 'xri', 'ymsgr', 'z39.50', 'z39.50r', 'z39.50s',
+    ];
+
+    /** @var array<string, true> Hash set for O(1) schema lookup */
+    private static array|null $schemaHashSet = null;
 
     public function resolve(LinkInlineNode $node, RenderContext $renderContext, Messages $messages): bool
     {
@@ -51,8 +111,8 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
             return true;
         }
 
-        $url = parse_url($node->getTargetReference(), PHP_URL_SCHEME);
-        if ($url !== null && $url !== false && preg_match('/^' . self::SUPPORTED_SCHEMAS . '$/', $url)) {
+        $scheme = parse_url($node->getTargetReference(), PHP_URL_SCHEME);
+        if ($scheme !== null && $scheme !== false && self::isSupportedScheme($scheme)) {
             $node->setUrl($node->getTargetReference());
 
             return true;
@@ -61,6 +121,20 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
         return false;
     }
 
+    /**
+     * Check if a URI scheme is supported using O(1) hash set lookup.
+     *
+     * This is ~6x faster than regex matching against the 371 IANA schemes.
+     */
+    private static function isSupportedScheme(string $scheme): bool
+    {
+        if (self::$schemaHashSet === null) {
+            self::$schemaHashSet = array_fill_keys(self::SUPPORTED_SCHEMAS_LIST, true);
+        }
+
+        return isset(self::$schemaHashSet[$scheme]);
+    }
+
     public static function getPriority(): int
     {
         return self::PRIORITY;

packages/guides/src/ReferenceResolvers/SluggerAnchorNormalizer.php

@@ -19,11 +19,28 @@
 
 final class SluggerAnchorNormalizer implements AnchorNormalizer
 {
+    private AsciiSlugger|null $slugger = null;
+
+    /** @var array<string, string> */
+    private array $cache = [];
+
     public function reduceAnchor(string $rawAnchor): string
     {
-        $slugger = new AsciiSlugger();
-        $slug = $slugger->slug($rawAnchor);
+        // Check cache first - same anchors are resolved many times
+        if (isset($this->cache[$rawAnchor])) {
+            return $this->cache[$rawAnchor];
+        }
+
+        if ($this->slugger === null) {
+            $this->slugger = new AsciiSlugger();
+        }
+
+        $slug = $this->slugger->slug($rawAnchor);
+        $result = strtolower($slug->toString());
+
+        // Cache the result for future calls
+        $this->cache[$rawAnchor] = $result;
 
-        return strtolower($slug->toString());
+        return $result;
     }
 }