*/ public static function defaults(): array { return array( 'enabled' => true, 'intro' => '', 'post_types' => array( 'page', 'post' ), 'max_items' => 50, 'include_tax' => true, 'full_enabled' => true, 'full_max_items' => 60, // Curated pages, pinned to the top in this exact order. The single // most valuable field on the whole screen: an assistant reads from // the top down and rarely reaches item forty. 'key_pages' => array(), 'key_label' => '', // How you want to be described and credited when you are quoted. // An assistant that has been told the preferred wording tends to // use it; one that has not will invent something. 'brand' => '', 'summary' => '', 'citation' => '', 'contact' => '', 'license' => '', // Machine-readable pointers so an assistant can go deeper without // guessing at URLs. 'link_sitemap' => true, 'link_feed' => false, 'declare_lang' => true, // Anything the generator cannot know: products, pricing, service // areas, disambiguation from a similarly named company. 'extra' => '', ); } /** * Rough token estimate for a body of text. * * Assistants read llms.txt inside a context window, so length is a real * constraint rather than a curiosity — a file that does not fit is a file * that gets truncated at whatever line the window ends on. ~4 characters * per token is the usual English approximation and close enough to warn on. */ public static function tokens( string $body ): int { return (int) ceil( mb_strlen( $body ) / 4 ); } /** * The three things Lighthouse checks, checked the same way. * * Google's "Agentic Browsing" category scores llms.txt with three regular * expressions over the raw bytes (core/audits/agentic/llms-txt.js): a line * starting with a single "# ", a markdown link anywhere, and at least 50 * characters. Any one of them missing scores the audit zero, and the trap * is the middle one — a file can be full of URLs and still fail, because * a bare URL is not a link to that expression. * * Copied here rather than described, so the screen tells the customer what * the report will tell them, before they run it. * * @param string $body A generated file. * @return array */ public static function lighthouse( string $body ): array { return array( 'h1' => (bool) preg_match( '/^\s*#\s+.+/m', $body ), 'link' => (bool) preg_match( '/\[.+\]\(.+\)/', $body ), 'length' => strlen( $body ) >= 50, ); } /** * Generate the llms.txt body. */ public function generate(): string { $settings = $this->options->get( 'llms_txt', self::defaults() ); $name = get_bloginfo( 'name' ); $tagline = get_bloginfo( 'description' ); $intro = trim( (string) $settings['intro'] ); $brand = trim( (string) ( $settings['brand'] ?? '' ) ); if ( '' !== $brand ) { $name = $brand; } $lines = array(); $lines[] = '# ' . $name; // The blockquote directly under the H1 is what an assistant quotes back // when asked "what is this site?". A curated summary beats the tagline. $summary = trim( (string) ( $settings['summary'] ?? '' ) ); $lead = '' !== $summary ? $summary : $tagline; if ( '' !== $lead ) { $lines[] = ''; $lines[] = '> ' . $lead; } if ( '' !== $intro ) { $lines[] = ''; $lines[] = $intro; } $facts = $this->fact_block( $settings ); if ( ! empty( $facts ) ) { $lines[] = ''; $lines = array_merge( $lines, $facts ); } $sections = array(); // Curated pages first and in the author's order — everything below is // generated, this part is edited. $key = $this->key_page_items( $settings ); if ( ! empty( $key ) ) { $label = trim( (string) ( $settings['key_label'] ?? '' ) ); $sections[ '' !== $label ? $label : __( 'Start here', 'ai-rank-suite' ) ] = $key; } // Key pages first (front, static pages by menu order), then posts. foreach ( (array) $settings['post_types'] as $post_type ) { $posts = get_posts( array( 'post_type' => $post_type, 'post_status' => 'publish', 'posts_per_page' => min( 200, (int) $settings['max_items'] ), 'orderby' => 'page' === $post_type ? 'menu_order' : 'date', 'order' => 'page' === $post_type ? 'ASC' : 'DESC', 'suppress_filters' => false, 'meta_query' => array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query 'relation' => 'OR', array( 'key' => '_airanksuite_exclude', 'compare' => 'NOT EXISTS', ), array( 'key' => '_airanksuite_exclude', 'value' => '1', 'compare' => '!=', ), ), ) ); if ( empty( $posts ) ) { continue; } $obj = get_post_type_object( $post_type ); $label = $obj ? $obj->labels->name : ucfirst( $post_type ); $items = array_map( array( $this, 'line_for_post' ), $posts ); $sections[ $label ] = $items; } if ( ! empty( $settings['include_tax'] ) ) { $cats = get_categories( array( 'hide_empty' => true, 'number' => 20 ) ); if ( ! empty( $cats ) ) { $items = array(); foreach ( $cats as $cat ) { $items[] = $this->line( $cat->name, get_category_link( $cat ), $cat->description ); } $sections[ __( 'Topics', 'ai-rank-suite' ) ] = $items; } } /** * Filter llms.txt sections before rendering. * * @param array $sections Section label => list of markdown lines. */ $sections = (array) apply_filters( 'airanksuite/llms_txt/sections', $sections ); foreach ( $sections as $label => $items ) { $lines[] = ''; $lines[] = '## ' . $label; $lines[] = ''; foreach ( (array) $items as $item ) { $lines[] = $item; } } $extra = trim( (string) ( $settings['extra'] ?? '' ) ); if ( '' !== $extra ) { $lines[] = ''; $lines[] = $extra; } $lines = self::ensure_link( $lines ); $lines[] = ''; $lines[] = sprintf( '', AIRANKSUITE_VERSION, gmdate( 'c' ) ); /** * Filter the final llms.txt body immediately before it is served. * * The last hook in the chain: everything else has already run, so * this is where a site appends a licence line, a contact block, or * anything the section filters cannot express. * * @param string $body The complete file. * @param bool $full Whether this is llms-full.txt. */ return (string) apply_filters( 'airanksuite/llms_txt/body', implode( "\n", $lines ) . "\n", false ); } /** * The facts an assistant cannot infer from a list of links: who you are, * how to credit you, where to ask, what reuse is permitted, and where the * machine-readable indexes live. * * @param array $settings Module settings. * @return array */ private function fact_block( array $settings ): array { $out = array(); // The canonical address of the site this file describes. // // Two reasons it is unconditional. An llms.txt is read detached from // wherever it was fetched — the assistant has the text, not the // origin — so the file has to say which site it speaks for. And it is // the one link that exists on every installation, including the one // with nothing published yet: Lighthouse's llms.txt audit fails a file // with no markdown link in it, and "no content yet" is exactly when an // owner runs their first report. $out[] = '- **Website:** ' . self::link( self::host(), home_url( '/' ) ); $citation = trim( (string) ( $settings['citation'] ?? '' ) ); if ( '' !== $citation ) { $out[] = '- **Preferred citation:** ' . $citation; } $contact = trim( (string) ( $settings['contact'] ?? '' ) ); if ( '' !== $contact ) { $out[] = '- **Contact:** ' . $contact; } $license = trim( (string) ( $settings['license'] ?? '' ) ); if ( '' !== $license ) { $out[] = '- **Content usage:** ' . $license; } if ( ! empty( $settings['declare_lang'] ) ) { $out[] = '- **Language:** ' . get_bloginfo( 'language' ); } // Markdown links, not bare URLs. A reader follows either; a parser // only follows the first, and Lighthouse's audit only counts the first. if ( ! empty( $settings['link_sitemap'] ) && get_option( 'permalink_structure' ) ) { $out[] = '- **Sitemap:** ' . self::link( 'sitemap.xml', home_url( '/sitemap.xml' ) ); } if ( ! empty( $settings['link_feed'] ) ) { $out[] = '- **Feed:** ' . self::link( __( 'RSS', 'ai-rank-suite' ), (string) get_feed_link() ); } // A list, not a run of lines. Markdown joins consecutive lines into one // paragraph, so "**Language:** en-US" and "**Sitemap:** …" rendered as // a single sentence with bold words in it. Each fact is an item. return empty( $out ) ? array() : $out; } /** * Curated key pages, in the order the customer arranged them. * * @param array $settings Module settings. * @return array */ private function key_page_items( array $settings ): array { $ids = array_values( array_filter( array_map( 'absint', (array) ( $settings['key_pages'] ?? array() ) ) ) ); if ( empty( $ids ) ) { return array(); } $items = array(); foreach ( array_slice( $ids, 0, 20 ) as $id ) { $post = get_post( $id ); if ( ! $post instanceof \WP_Post || 'publish' !== $post->post_status ) { continue; } /** * Decide per post whether it appears in llms.txt at all. * * The meta box covers the common case; this covers the rules — a * whole taxonomy term, everything under a date, anything a query * can express but a checkbox cannot. * * @param bool $exclude Whether to leave this post out. * @param WP_Post $post The post. */ if ( (bool) apply_filters( 'airanksuite/llms_txt/exclude', false, $post ) ) { continue; } $items[] = $this->line_for_post( $post ); } return $items; } /** * Generate the llms-full.txt body: full content of included pages as markdown. */ public function generate_full(): string { $settings = $this->options->get( 'llms_txt', self::defaults() ); $lines = array(); $lines[] = '# ' . get_bloginfo( 'name' ) . ' — ' . __( 'Full content', 'ai-rank-suite' ); $tagline = get_bloginfo( 'description' ); if ( '' !== $tagline ) { $lines[] = ''; $lines[] = '> ' . $tagline; } $lines[] = ''; $lines[] = '**Website:** ' . self::link( self::host(), home_url( '/' ) ); $lines[] = ''; $lines[] = sprintf( /* translators: %s: link to the short llms.txt */ __( 'This file contains the full text of the most important pages. A curated index is available at %s.', 'ai-rank-suite' ), self::link( 'llms.txt', home_url( '/llms.txt' ) ) ); foreach ( $this->included_posts( $settings, (int) $settings['full_max_items'] ) as $post ) { $lines[] = ''; $lines[] = '---'; $lines[] = ''; $lines[] = '## ' . \AiRankSuite\Support\Html::text( get_the_title( $post ) ); $lines[] = ''; // The source as a markdown link: this is the line that lets an // assistant cite the page it just read, and a bare URL is not a // link to anything that parses markdown. $permalink = (string) get_permalink( $post ); $lines[] = '**' . __( 'URL:', 'ai-rank-suite' ) . '** ' . self::link( $permalink, $permalink ); $modified = get_post_modified_time( 'Y-m-d', true, $post ); if ( $modified ) { $lines[] = ''; $lines[] = '**' . __( 'Last updated:', 'ai-rank-suite' ) . '** ' . $modified; } $summary = get_post_meta( $post->ID, '_airanksuite_ai_summary', true ); if ( ! is_string( $summary ) || '' === $summary ) { $summary = (string) $post->post_excerpt; } $summary = \AiRankSuite\Support\Html::without_private( $summary ); if ( '' !== trim( $summary ) ) { $lines[] = ''; $lines[] = '> ' . trim( (string) preg_replace( '/\s+/', ' ', \AiRankSuite\Support\Html::text( $summary ) ) ); } $lines[] = ''; $lines[] = \AiRankSuite\Support\Html::to_markdown( \AiRankSuite\Support\Html::without_private( \AiRankSuite\Support\Html::rendered( $post ) ) ); } $extra = trim( (string) ( $settings['extra'] ?? '' ) ); if ( '' !== $extra ) { $lines[] = ''; $lines[] = $extra; } $lines = self::ensure_link( $lines ); $lines[] = ''; $lines[] = sprintf( '', AIRANKSUITE_VERSION, gmdate( 'c' ) ); /** * Filter the final llms.txt body immediately before it is served. * * The last hook in the chain: everything else has already run, so * this is where a site appends a licence line, a contact block, or * anything the section filters cannot express. * * @param string $body The complete file. * @param bool $full Whether this is llms-full.txt. */ return (string) apply_filters( 'airanksuite/llms_txt/body', implode( "\n", $lines ) . "\n", true ); } /** * Posts included per settings (exclusions respected), ordered pages-first. * * @param array $settings Module settings. * @param int $limit Max posts. * @return array */ private function included_posts( array $settings, int $limit ): array { $posts = array(); foreach ( (array) $settings['post_types'] as $post_type ) { if ( count( $posts ) >= $limit ) { break; } $posts = array_merge( $posts, get_posts( array( 'post_type' => $post_type, 'post_status' => 'publish', 'posts_per_page' => $limit - count( $posts ), 'orderby' => 'page' === $post_type ? 'menu_order' : 'date', 'order' => 'page' === $post_type ? 'ASC' : 'DESC', 'suppress_filters' => false, 'meta_query' => array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query 'relation' => 'OR', array( 'key' => '_airanksuite_exclude', 'compare' => 'NOT EXISTS', ), array( 'key' => '_airanksuite_exclude', 'value' => '1', 'compare' => '!=', ), ), ) ) ); } return $posts; } /** * Markdown line for a post. * * @param WP_Post $post The post. */ private function line_for_post( WP_Post $post ): string { $summary = get_post_meta( $post->ID, '_airanksuite_ai_summary', true ); if ( ! is_string( $summary ) || '' === $summary ) { $summary = get_the_excerpt( $post ); } return $this->line( get_the_title( $post ), (string) get_permalink( $post ), (string) $summary ); } /** * A markdown inline link. * * Everything this file points at goes through here, because the one thing * a machine reader cannot do with a bare URL is tell it apart from the * sentence around it. Square brackets in the label would end the link * early, so they are stripped rather than escaped — a label is a name, and * no name needs them. * * @param string $label Link text. * @param string $url Target. */ private static function link( string $label, string $url ): string { $label = trim( str_replace( array( '[', ']' ), '', $label ) ); $url = esc_url_raw( $url ); if ( '' === $url ) { return $label; } return sprintf( '[%s](%s)', '' !== $label ? $label : $url, $url ); } /** The site's host, or its full address if the host cannot be read. */ private static function host(): string { $home = home_url( '/' ); $host = wp_parse_url( $home, PHP_URL_HOST ); return is_string( $host ) && '' !== $host ? $host : $home; } /** * Guarantee the file contains at least one markdown link. * * The lines above already put one in — but they are built from settings a * customer can switch off and from a filter a site can rewrite, and the * cost of being wrong is the whole Lighthouse audit scoring zero. This is * the floor: a file that ended up with nothing to follow gets the one link * that always exists. * * Deliberately before the body filter. A site that strips our links after * this has decided to; a site that simply has no content has not. * * @param array $lines Assembled document. * @return array */ private static function ensure_link( array $lines ): array { if ( preg_match( '/\[.+\]\(.+\)/', implode( "\n", $lines ) ) ) { return $lines; } $lines[] = ''; $lines[] = '## ' . __( 'Site', 'ai-rank-suite' ); $lines[] = ''; $lines[] = '- ' . self::link( self::host(), home_url( '/' ) ) . ': ' . __( 'The site this file describes.', 'ai-rank-suite' ); return $lines; } /** * Build "- [Title](url): description". * * @param string $title Title. * @param string $url URL. * @param string $desc Description. */ private function line( string $title, string $url, string $desc = '' ): string { // A passage marked private is marked "do not give this to a model". // This file is the one models fetch first, so it is the last place it // may appear — an excerpt written by hand goes out exactly as typed // unless somebody takes it out here. $title = \AiRankSuite\Support\Html::without_private( $title ); $desc = \AiRankSuite\Support\Html::without_private( $desc ); $title = html_entity_decode( wp_strip_all_tags( $title ), ENT_QUOTES | ENT_HTML5, 'UTF-8' ); $desc = html_entity_decode( wp_strip_all_tags( $desc ), ENT_QUOTES | ENT_HTML5, 'UTF-8' ); $desc = trim( preg_replace( '/\s+/', ' ', $desc ) ?? '' ); if ( function_exists( 'mb_substr' ) && mb_strlen( $desc ) > 200 ) { $desc = mb_substr( $desc, 0, 197 ) . '…'; } $line = sprintf( '- [%s](%s)', $title, esc_url_raw( $url ) ); return '' !== $desc ? $line . ': ' . $desc : $line; } }