diff --git a/README.md b/README.md index 6ec0b92..ced99b7 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,23 @@ -# Meta Knight – SEO for Kirby +

Meta Knight – SEO for Kirby

-Meta Knight is a SEO and Social Media Sharing Plugin for [Kirby](https://getkirby.com). Meta Knight makes it easier to work with meta information in Kirby's panel. +

🔍 Manage SEO and Social Media Sharing from the Kirby panel

+ +
+ +

+Screenshot showing the many config fields for titles, descriptions and similar info in the panel +

+ +
+ +--- + +
+
Meta Knight provides blueprints, snippets and custom preview sections. At the moment the plugin covers: @@ -11,179 +28,301 @@ Meta Knight provides blueprints, snippets and custom preview sections. At the mo All of the above is neatly organized in a pre-composed SEO tab that can easily be added to any blueprint. -![Screenshot](screenshot.gif) +
-This plugin was originally developed at [diesdas.digital](https://www.diesdas.digital) by Jonathan Muth, Lorenz Seeger and Leslie Büttel. Meta Knight exists because we wanted to standardize the way we handle meta information across all our projects. +- [Installation](#installation) +- [Setup](#setup) +- [Configuration](#configuration) + - [Title options](#title-options) + - [Homepage options](#homepage-options) + - [Canonical URLs](#canonical-urls) +- [Sourcing SEO data from existing page content](#sourcing-seo-data-from-existing-page-content) +- [Other](#other) + - [Development](#development) + - [License](#license) + - [Credits](#credits) -We'd also like to thank @distantnative for his help along the way! Without him this plugin wouldn't be what it is today. +
+ +## Installation -## Config options +You can install Meta Knight via -### Site title +1. **Manual download** -#### Order +Download and copy this repository to `/site/plugins/kirby-meta-knight`. -By default the _Page Title_ will be rendered before the _Site Title_. Resulting in a title tag that looks like this: `Page Title – Site Title`. If you want the _Site Title_ to come first, simply add the following lines to your Kirby `config.php` file: +2. **Git Submodule** +```bash +git submodule add https://github.com/diesdasdigital/kirby-meta-knight.git site/plugins/kirby-meta-knight ``` -'diesdasdigital.meta-knight' => [ - 'siteTitleAfterPageTitle' => false, -], + +3. **Composer** + +```bash +composer require diesdasdigital/kirby-meta-knight ``` -You'll then get a title tag that looks like this: `Site Title – Page Title`. +
-#### Customize home page title +## Setup -By default the title tag of the home page will include both the _page title_ and the _site title_ and look like this: `Page Title – Site Title`. If you want to only display the site title on the homepage, simply add the following lines to your Kirby `config.php` file: +After installation, follow these steps to setup your site: -``` -'diesdasdigital.meta-knight' => [ - 'siteTitleAsHomePageTitle' => true, -], +**1. Add the SEO tab definition `seotab: seo` to the `tabs` section of your site's blueprint:** +(Meta Knight uses meta information configured on the site level as fallback for individual pages) + +```yaml +title: Site + +tabs: + content: + icon: grid + label: Overview + sections: + drafts: + type: pages + status: draft + create: default + published: + type: pages + status: published + seotab: seo ``` -The title tage of your home page will then look like this: `Site Title` +**2. Add the SEO tab definition `seotab: seo` to the `tabs` section of your page blueprints:** -The same can be done with the page title on the homepage +```yaml +title: Default +icon: 📃 +tabs: + content: + icon: text + columns: + - width: 2/3 + fields: + text: + type: blocks + - width: 1/3 + sections: + pages: + status: all + layout: list + files: + layout: list + seotab: seo ``` -'diesdasdigital.meta-knight' => [ - 'pageTitleAsHomePageTitle' => true, -], + +**3. Add these snippets to the `` area of your templates:** + +```php + + ``` -will result in `Page Title` +✔ Now the panel is set up so you can enter SEO information, which the snippets then render when a page is displayed. -Keep in mind: Both options cannot be enabled at the same time. +
-### Customizeable `page title | site title` separator +## Configuration -The separator between page title and site title can be customized like this: +There are several configuration options available. They can be placed under the key `diesdasdigital.meta-knight` in your `config.php`: -``` -'diesdasdigital.meta-knight' => [ - 'separator' => ' \o/ ', -], +```php + [ + 'seperator' => ' - ', + 'siteTitleAfterPageTitle' => true, + 'siteTitleAsHomePageTitle' => false, + 'pageTitleAsHomePageTitle' => false, + 'canonicalURLIncludesWWW' => false, + ], +]; ``` -The default value is ` | `. +### Title options -### Canonical URLs +By default, the title will include the page title followed by the site title, divided by a separator: `My Page – My Site`. You can flip the order and customize the separator: -Meta Knight gives you control over how the auto-generated canonical URLs for your pages are rendered. By default canonical URLs do not include the `www.` subdomain. If you wish the canonical URLs to include `www.` please set the following option in config.php: +#### `seperator` -``` -'diesdasdigital.meta-knight' => [ - 'canonicalURLIncludesWWW' => true, -], -``` +Set a custom separator, e.g. ` | `: `My Page | My Site`. +Default: ` - ` -Please note: +#### `siteTitleAfterPageTitle` -- Auto-generated canonical URLs will always be the `https://` version of any given page. -- Do not enable `canonicalURLIncludesWWW` if your Kirby site is running on another subdomain. -- A canonical URL that was manually entered in the SEO Tab will always override the auto-generated canonical URL of any given page. +If set to `false`, outputs the site title first: `My Site – My Page`. +Default: `true` +### Homepage title +If you want a plain, single title for the homepage instead of a combination of page and site titles, you can use one of these options: ---- +#### `siteTitleAsHomePageTitle` -## Installation +If set to `true`, only display the site title for the homepage: `My Site`. +Default: `false` -### Download +#### `pageTitleAsHomePageTitle` -Download and copy this repository to `/site/plugins/kirby-meta-knight`. +If set to `true`, only display the page title for the homepage: `Home`. +Default: `false` -### Git submodule +> ⚠ Note that the two options are mutually exclusive, you may only set one of them to `true`. -```bash -git submodule add https://github.com/diesdasdigital/kirby-meta-knight.git site/plugins/kirby-meta-knight -``` +### Canonical URLs -### Composer +Meta Knight automatically normalizes page URLs for use as canonical URL, stripping the `www.` in the beginning and enforcing `https` as protocol. If you want your canonical URLs to include the `www` subdomain, use: -```bash -composer require diesdasdigital/kirby-meta-knight -``` +#### `canonicalURLIncludesWWW` -## Setup +If set to `true`, `www.` is added to the beginning of canonical URLs. Otherwise it is stripped. +Default: `false` + +> **Please note** ⚠️ +> +> - Auto-generated canonical URLs will always use the `https` protocol. +> - A canonical URL manually entered in the SEO Tab will override the auto-generated one. +> - Do not enable `canonicalURLIncludesWWW` if your site is running on another subdomain! -How to add Meta Knight to Kirby: +
-1. Add this tab to your site's blueprint (site.yml): `seotab: seo` (Meta Knight uses the site's meta information as a fall back when no meta information is provided for a page) +## Sourcing SEO data from existing page content -2. Add this tab to all your page blueprints: `seotab: seo` +Sometimes you don't want to configure each description or sharing image manually, but instead automatically reuse a project thumbnail or use an excerpt of the page content for the description. -3. Add these two snippets to your head: `` + `` +For this, you can use Kirby [Page Models](https://getkirby.com/docs/guide/templates/page-models) to override the methods used by Meta Knight to read the data. You can inspect the methods Meta Knight uses to access data in [`snippets/meta_information.php`](snippets/meta_information.php). + +```php +or($your_fallback_here); + } +} +``` -Example: +> ⚠ Make sure the overridden methods continue to return `Kirby\Cms\Field` objects! (check the example for details) + +### Example + +A portfolio site has project pages, showcasing a `project_image` alongside a `project_description`. The respective blueprint in `site/blueprints/pages/project.yml` looks like this: ```yaml -title: Site +title: Project tabs: content: icon: text - label: Content - sections: - drafts: - headline: Drafts - type: pages - status: draft - templates: - - default - - masthead - image: - query: false - unlisted: - headline: Unlisted - type: pages - status: unlisted - image: - query: false - listed: - headline: Listed - type: pages - status: listed - image: - query: false - + fields: + project_image: + label: Project Image + type: files + multiple: false + project_description: + label: Project Description + type: blocks seotab: seo ``` -## Options +We want Meta Knight to use the project image as the sharing image for Twitter and Facebook, if no other image is explicitly configured in the SEO tab. To extend the page model and adjust the methods, we need to create `site/models/project.php`: + +```php +or(parent::project_image()); + } + public function og_image() { + return parent::og_image()->or(parent::project_image()); + } + public function twitter_image() { + return parent::twitter_image()->or(parent::project_image()); + } +} +``` -Currently the plugin isn't configurable via the `config.php` file. This is something we are thinking about adding in a future release. +Now, the page will use the `meta_image`, `og_image` and `twitter_image` fields if they were configured in the SEO tab, but use the `->or()` method to default to the `project_image` if the former isn't set! -## Development +Let's continue and make sure the project description is used as the SEO description. If we did everything as with the images above, our method on the class `ProjectPage` would look like this: + +```php + // ❌ doesn't work! +public function meta_description() { + return parent::meta_description()->or(parent::project_description()); +} +``` + +However, this doesn't work. The value of `project_description` isn't directly usable by Meta Knight because it is a complex field of type `blocks`. We can call `->toBlocks()->excerpt()` on the field to get a usable text value for our SEO description: + +```php +// ❌ better, but still errors! +public function meta_description() { + $excerpt = parent::project_description()->toBlocks()->excerpt(); + return parent::meta_description()->or($excerpt); +} +``` + +Unfortunately, there are still errors. The excerpt method returns a plain `string` value, but Meta Knight expects a `Kirby\Cms\Field` object to be returned. It needs to call methods like `->or()` and `->value()` during rendering, which aren't available on regular strings. So we need to wrap our description string in a new `Field` object: + +```php +toBlocks()->excerpt()); + return parent::meta_description()->or($excerpt); + } +} +``` + +Now the excerpt sourced from a page's `project_description` is displayed in the SEO snippet alongside the `project_image`! +You can use the same approach to provide defaults for snippet titles, author data and any other meta information. + +
+ +## Other ### Development -You can start the dev process with … +#### Install dependencies ```bash -yarn dev +yarn ``` -This will automatically update the `index.js` and `index.css` of Meta Knight as soon as you make changes. -It will also enable hot module reloading in the panel. Reload the panel once and afterwards you should -see changes immediately without further reloading. +#### Start development server -### Production +```bash +yarn dev +``` -As soon as you are happy with the changed you've made to Meta Knight, you should build the final version with +This will automatically rebuild the `index.js` and `index.css` of Meta Knight as soon as you make changes. + +#### Build for production ```bash yarn build ``` -This will automatically create a minified and optimized version of your `index.js` and `index.css` that will improve load time in production environments. +This will build minified and optimized versions of your `index.js` and `index.css` files, improving load time in production environments. + +### License -## License +MIT – See [LICENSE.md](LICENSE.md) for more info. -MIT – See LICENSE.md for more info. +### Credits -## Credits +This plugin was originally developed at [diesdas.digital](https://www.diesdas.digital) by Jonathan Muth, Lorenz Seeger and Leslie Büttel. Meta Knight exists because we wanted to standardize the way we handle meta information across all our projects. + +We'd also like to thank @distantnative for his help along the way! Without him this plugin wouldn't be what it is today. -- [diesdas ⚡️ digital](https://github.com/diesdasdigital) +GitHub: [diesdas ⚡️ digital](https://github.com/diesdasdigital)