SEO Pro Docs

content/collections/sections/seo-pro.md

@@ -0,0 +1,7 @@
+---
+id: b2dfa5a7-326a-462f-bfa4-f6a06b589c3a
+blueprint: sections
+title: 'SEO Pro'
+template: seo-pro.index
+section: seo_pro
+---

content/collections/seo_pro.yaml

@@ -0,0 +1,18 @@
+title: 'SEO Pro'
+template: page
+layout: layout
+mount: b2dfa5a7-326a-462f-bfa4-f6a06b589c3a
+revisions: false
+route: 'seo-pro/{slug}'
+sort_dir: asc
+date_behavior:
+  past: public
+  future: private
+preview_targets:
+  -
+    label: Entry
+    url: '{permalink}'
+    refresh: true
+inject:
+  blueprint: page
+  section: seo_pro

content/collections/seo_pro/advanced-configuration.md

@@ -0,0 +1,46 @@
+---
+id: 1917f8a1-4b89-410b-ba3d-20d85bcc9ded
+blueprint: seo_pro
+title: 'Advanced Configuration'
+---
+## Publishing Config
+
+You can publish SEO Pro's config for modification by running the following:
+
+```bash
+php artisan vendor:publish --tag="seo-pro-config"
+```
+
+## Publishing Views
+
+You can publish SEO Pro's `sitemap.xml` and `humans.txt` views for modification by running the following:
+
+```bash
+php artisan vendor:publish --tag="seo-pro-views"
+```
+
+These views will be published into your `resources/views/vendor/seo-pro` directory for modification.
+
+You may also override the default `meta.antlers.html` view, though it is not published by default. ***Important Note***: Overriding this view will require you to be mindful of updates as it will not be automatically maintained for you.
+
+## Sitemap.xml
+
+A `sitemap.xml` route is automatically generated for you.
+
+If you disable SEO on the section or item level, the relevant section/item will automatically be discluded from the sitemap.
+
+If you wish to completely disable the sitemap, change it's URL, or customize it's cache expiry, you can [publish the SEO Pro config](/seo-pro/advanced-configuration) and modify these settings within `config/statamic/seo-pro.php`.
+
+If you wish to customize the contents of the `sitemap.xml` view, you may also [publish the SEO Pro views](/seo-pro/advanced-configuration#publishing-views) and modify the provided antlers templates within your `resources/views/vendor/seo-pro` folder.
+
+## Pagination Meta
+
+By default, `canonical` URL meta will show pagination on `?page=2` and higher, with `rel="prev"` / `rel="next"` links when appropriate.
+
+If you wish to customize or disable pagination, you can [publish the SEO Pro config](/seo-pro/advanced-configuration) and modify these settings within `config/statamic/seo-pro.php`.
+
+## Twitter Card Meta
+
+By default, `twitter:card` meta will be rendered using `summary_large_image`.
+
+If you wish to change this to `summary`, you can [publish the SEO Pro config](/seo-pro/advanced-configuration) and modify your twitter card within `config/statamic/seo-pro.php`.

content/collections/seo_pro/available-commands.md

@@ -0,0 +1,79 @@
+---
+id: c7b6e4b0-15ac-4301-842f-61cabf36c1e7
+blueprint: seo_pro
+title: 'Available Commands'
+intro: 'The following commands are available to assist with setup or managing entry link metadata, keywords, and embeddings.'
+---
+## `seo-pro:links-setup`
+
+Asssists with configuring Content Linking features on a new installation. For more information, reading [reading the configuration steps](/seo-pro/content-linking-setup#using-the-seoprolinkssetup-command) within the [Setup & Config](/seo-pro/content-linking-setup) guide.
+
+To run this command, run the following from the root of your project:
+
+```bash
+php please seo-pro:links-setup
+```
+
+## `seo-pro:analyze-content`
+
+The `analyze-content` command may be used to crawl and generate the required records for each entry within your site.
+
+To run this command, run the following from the root of your project:
+
+```bash
+php please seo-pro:analyze-content
+```
+
+This command has the same effect as running the following commands, in this order:
+
+```bash
+php please seo-pro:scan-links
+php please seo-pro:generate-keywords
+php please seo-pro:generate-embeddings
+```
+
+## `seo-pro:generate-embeddings`
+
+The `generate-embeddings` command may be used to create records within the `seopro_entry_embeddings` database table. This command will call the configured embeddings API.
+
+To create embeddings, run the following from the root of your project:
+
+```bash
+php please seo-pro:generate-embeddings
+```
+
+This command will *not* regenerate embeddings if the configuration has not changed, or if the entry's content has not changed.
+
+## `seo-pro:generate-keywords`
+
+The `generate-keywords` command may be used to generate records within the `seopro_entry_keywords` database table.
+
+To generate entry keywords, run the following from the root of your project:
+
+```bash
+php please seo-pro:generate-keywords
+```
+
+This command will *not* regenerate keywords if the configuration has not changed, or if the entry's content has not changed.
+
+## `seo-pro:scan-links`
+
+The `scan-links` command may be used to generate records within the `seopro_entry_links` database table. This command will crawl all eligible entries within your sites and parse their content.
+
+To run this command, run the following from the root of your project:
+
+```bash
+php please seo-pro:scan-links
+```
+
+This command will *not* regenerate keywords if the configuration has not changed, or if the entry's content has not changed.
+
+## `seo-pro:sync-entry-links`
+
+SEO Pro stores some entry metadata, such as the title and URI, within the `seopro_entry_links` database table for performance reasons. If you are making changes directly within flat-files, this metadata can become out of sync.
+
+To sync entry metadata, run the following from the root of your project:
+
+```bash
+php please seo-pro:sync-entry-links
+```

content/collections/seo_pro/available-hooks.md

@@ -0,0 +1,33 @@
+---
+id: 41cd0830-04f4-43bd-875e-46f0d608be9e
+blueprint: seo_pro
+title: 'Available Hooks'
+intro: 'Hooks are a powerful extension feature of Statamic, and SEO Pro provides a few Content Linking hooks. To learn more about Hooks, consider reading [their associated documentation](/extending/hooks).'
+---
+## Link Manager Index Query: `query`
+
+Triggered before the index query for the Link Manager table is executed. The payload will be an object with a `query` property.
+
+```php
+use Statamic\SeoPro\Hooks\CP\EntryLinksIndexQuery;
+
+EntryLinksIndexQuery::hook('query', function ($payload, $next) {
+  $payload->query; // a QueryBuilder instance.
+
+  return $next($payload);
+});
+```
+
+## Global Automatic Links Index Query: `query`
+
+Triggered before the index query for the Global Automatic Links table is executed. The payload will be an object with a `query` property.
+
+```php
+use Statamic\SeoPro\Hooks\CP\AutomaticLinksIndexQuery;
+
+AutomaticLinksIndexQuery::hook('query', function ($payload, $next) {
+  $payload->query; // a QueryBuilder instance.
+
+  return $next($payload);
+});
+```

content/collections/seo_pro/collection-configuration.md

@@ -0,0 +1,73 @@
+---
+id: 245b78ff-2860-473d-a700-8c1eaed30d39
+blueprint: seo_pro
+title: 'Collection Configuration'
+intro: 'In addition to the [core Content Linking configuration](/seo-pro/content-linking-setup#seo-pro-configuration-file-updates), SEO Pro allows you to fine-tune linking behavior for each collection as well as decide which collections should not be analyzed.'
+---
+## Disabling Content Linking features for collections
+
+Depending on how much content your site has, you may wish to disable Content Linking features on some collections for performance reasons or disable analysis on sensitive collections, such as products, orders, or other similar types of data.
+
+There are two ways to disable collections: by updating the PHP configuration file and within the Control Panel.
+
+### Disabling collections within the config file
+
+To disable collections using the PHP configuration file, add the collection handles to the `linking.disabled_collections` value within the configuration file.
+
+Collections disabled this way will *not* be used when generating embeddings and keywords, or when suggesting related content, even if someone somehow enables them through the Control Panel.
+
+```php
+<?php
+
+return [
+
+    // Other SEO Pro configuration.
+
+    'linking' => [
+
+        // Other linking configuration.
+
+        'disabled_collections' => [
+            'products',
+            'orders',
+            'feedback',
+        ],
+
+    ],
+];
+```
+
+
+### Disabling collections within the Control Panel
+
+The second method is through the Statamic Control Panel. From within the SEO Pro Link Manager, activate the dropdown in the upper right-hand corner of the screen to reveal additional options. From the options that appear, select "Collection Linking Behavior":
+
+![Locating Collection Linking Behavior](/img/seo-pro/collection-linking-behavior.png)
+
+From the list of available collections, activate the actions dropdown menu to the right of the collection to update and select "Edit Linking Behavior":
+
+![Editing collection linking behavior](/img/seo-pro/edit-collection-linking-behavior.png)
+
+On the panel that appears, adjust the "Linking Enabled" option to the desired value and click "Save":
+
+![Collection Linking Enabled Setting](/img/seo-pro/collection-allow-linking-toggle.png)
+
+## Restricting collection suggestions
+
+Additionally, SEO Pro allows you to determine *which* collections should be considered when preparing link suggestions. For example, if a site contains a `blog`, `articles`, `pages`, and `knowledge_base` collection, you could configure the `blog` collection to only receive suggestions from the `blog` and `articles` collections, ignoring any other collection. Similarly, if you are using [Multi-site](/multi-site), you can disable suggestions across sites.
+
+On the Collection Linking Behavior page, select the "Edit Linking Behavior" option from the actions menu next to the collection you'd like to update. On the stack panel that appears, you may adjust the following values:
+
+* **Linking Enabled**: Determines if content linking is enabled for the collection.
+* **Allow Cross-Site Suggestions**: Determines if SEO Pro should suggest link suggestions across sites when using Multi-site.
+* **Allow Suggestions from All Collections**: When toggled to `false`, you will be able to select individual collections that will be used when retrieving suggested content or looking for linking opportunities.
+
+![Restricting collection suggestions](/img/seo-pro/restricting-collection-suggestions.png)
+
+Collection configuration changes made within the Control Panel are stored within the `seopro_collection_link_settings` database table.
+
+## Resetting collection configuration
+
+To reset a collection's configuration to its default values, select the "Reset Collection Settings" from the actions drop-down menu to the right of the desired collection:
+
+![Resetting collection settings](/img/seo-pro/resetting-collection-settings.png)

content/collections/seo_pro/content-linking-faq.md

@@ -0,0 +1,112 @@
+---
+id: 2efde67f-35b2-40fd-b54b-b53fb84e7c3a
+blueprint: seo_pro
+title: 'Content Linking FAQ and Troubleshooting'
+nav_title: FAQs/Troubleshooting
+intro: 'Answers to common questions and troubleshooting tips.'
+---
+## What are the *minimum* steps to setup Content Linking?
+
+After installing SEO Pro, the following are the minimum steps:
+
+1. Ensure a `default` database connection has been configured
+2. Publish and run SEO Pro's database migrations
+3. Add an OpenAI API key to the `.env` by adding the `SEO_PRO_OPENAI_API_KEY=<API_KEY>` entry
+4. Enable Content Linking by adding `SEO_PRO_LINKING_ENABLED=true` to the `.env` file
+5. Run the `php please seo-pro:analyze-content` command from the root of the project
+
+While this is the *fastest* way to get started, you may want to review the documentation for [disabling collections first](/seo-pro/collection-configuration).
+
+## Can I use Content Linking features *without* AI embeddings or OpenAI?
+
+The content linking features cannot be used without generating embeddings from entry content.
+
+Any OpenAI compatible embeddings API may be used. SEO Pro does not have a hard dependency on OpenAI, specifically.
+
+## Why are manual changes to flat-file entries not reflected in the Link Manager?
+
+Some information is cached within the `seopro_entry_links` database table for performance reasons. Entry titles and URIs can be synchronized by running the following command from the root of the project:
+
+```bash
+php please seo-pro:sync-entry-links
+```
+
+This command will also delete rows from the `seopro_entry_links` table if the entry no longer exists.
+
+## How do I exclude a specific entry from being suggested?
+
+To exclude a specific entry from being suggested, follow the [steps outlined here](/seo-pro/entry-configuration#preventing-the-entry-from-being-suggested).
+
+## Some collections are not appearing in suggested results
+
+Collections not appearing in results can be caused by a variety of things:
+
+* The collections are listed in the `statamic.seo-pro.linking.disabled_collections` configuration option within the `config/statamic/seo-pro.php` configuration file
+* The collections are not listed in any other collection's "Limit Suggestions From" configuration
+* The current user does not have permissions to view entries from the collections that are not appearing
+* The collection was added after initially setting up SEO Pro content linking features and keywords, link metadata, or embeddings have not been generated for that collection yet
+
+## The site's name, branding, or other repeatedly used phrased are appearing too often in suggestions.
+
+Phrases that are appear frequently within content, but provide no real value in terms of linking opportunities, should be added to each site's "Ignored Phrases" list. This list is added to the keyword and phrases "stop word" list.
+
+Updates to a site's ignored phrases list *are applied* when returning suggestions for specific entries. Because of this, the `seopro_entry_keywords` table does *not* need to be regenerated after making changes.
+
+## No entries are appearing in the Link Manager
+
+Entries not appearing within the Link Manager is most often caused by an empty `seopro_entry_links` database table. The simplest way to resolve this is by running the following command from the root of the project:
+
+```bash
+php please seo-pro:analyze-content
+```
+
+The `seo-pro:analyze-content` command will work to regenerate keywords, embeddings, and link meta data for all missing entries, or if the content has changed. If you'd like to target the `seopro_entry_links` table specifically, you may run the following command instead:
+
+```bash
+php please seo-pro:scan-link
+```
+
+## Entries are present in the Link Manager, but no suggestions are appearing
+
+The most common reason for no suggestions appearing is missing embeddings or keyword data. This can be regenerated by running the following command from the root of the project:
+
+```bash
+php please seo-pro:analyze-content
+```
+
+If both tables are already populated, and suggestions are still not appearing for an entry, this may be caused by any of the following:
+
+* There are missing values in the `seopro_entry_links` database table. Run `php please seo-pro:scan-links` to resolve this.
+* No more suggestions could be found within the keyword or related entry threshold limits. If a link already appears within the content, that entry will *not* be suggested again.
+* It is possible the content crawler is unable to find any content to parse. If pages do not contain `<article></article>` tags, a developer will need to use the `{{ seo_pro:content }}{{ /seo_pro:content }}` tag pair to mark the content to be parsed and analyzed.
+* A network or database related issue could be interfering with generating suggestions. This is possible on very large sites; adjusting which collections an entry can receive suggestions from may help if this is the case.
+
+## I have a custom fieldtype and links are not automatically inserted into nested fields.
+
+Content linking and automatic link insertion relies on an internal concept of "content mapping". SEO Pro utilizes this content mapping system to target specific fields and instruct the insertion/replacement engine on how to perform the content updates.
+
+Because of the varied nature of custom fieldtypes, SEO Pro's content mapper cannot make generalizations on how the content is structured, or how to update it in a safe way. For these reasons, custom fieldtypes would require their own custom content mapper and link insertion implementation.
+
+## Analyzing content is taking a long time.
+
+SEO Pro must retrieve the content and interact with third-party APIs, as well as extract keywords and phrases for each entry, which can take some time. To reduce the number of entries processed, consider restricting which collections are analyzed.
+
+## How do I customize the format of links inserted into Text, Textarea, and Markdown fieldtypes?
+
+SEO Pro uses templates when creating the link to insert into your site's output. You can override these templates by publishing the associated views with the following command:
+
+```bash
+ php artisan vendor:publish --tag=seo-pro-linking-views
+```
+
+After the command runs, you will find three new templates within your resources directory:
+
+* `vendor/seo-pro/links/automatic.antlers.html`: Determines the format of Global Automatic Links
+* `vendor/seo-pro/links/html.antlers.html`: Determines the format of links inserted into [Text](/fieldtypes/text) and [Textarea](/fieldtypes/textarea) fieldtypes
+* `vendor/seo-pro/links/markdown.antlers.html`: Determines the format of links inserted into the [Markdown](/fieldtypes/markdown) fieldtypes
+
+Modify the template associated with the fieldtype(s) you would like to adjust the format of.
+
+## How do I disable content mapping for a specific entry field?
+
+You may disable content mapping for a specific entry field [by following the steps listed in this guide](/seo-pro/parsing-content-and-content-mapping#disabling-content-mapping-for-a-field).