bnomei/kirby3-htmlhead

Kirby 3 Plugin for a best-practice HTML Head Element extendable with snippets.

Installs: 233

Dependents: 0

Suggesters: 1

Stars: 8

Watchers: 0

Forks: 1

Open Issues: 2

Type:kirby-plugin

2.0.0 2019-09-02 15:54 UTC

README

Release Stars Downloads Issues Build Status Coverage Status Maintainability Demo Gitter Twitter

Kirby 3 Plugin for a best-practice HTML Head Element extendable with snippets.

Commercial Usage

This plugin is free but if you use it in a commercial project please consider to

Installation

  • unzip master.zip as folder site/plugins/kirby3-htmlhead or
  • git submodule add https://github.com/bnomei/kirby3-htmlhead.git site/plugins/kirby3-htmlhead or
  • composer require bnomei/kirby3-htmlhead

Works well with

Usage

Page Method: htmlhead

In any template or your header snippet call the page method right after the tags that should come first.

-  <html>
+  <html <?= site()->attrLang() ?>>
   <body>
-      <meta charset="utf-8">
-      <meta http-equiv="x-ua-compatible" content="ie=edge">
-      <meta name="viewport" content="width=device-width, initial-scale=1 shrink-to-fit=no">
-      <base href="<?= site()->url() ?>'">'
-      <title><?= $page->title() ?></title>
+      <?= $page->htmlhead() ?>
+      <?= $page->metatags() ?>

TIP: $page->metatags() is from pedroborges/kirby-meta-tags which you will probably install for OpenGraph, Twitter and JSON-ld. But you will have to set the title and base option to null since htmlhead provides these as well.

You can also override any defaults in forwarding the new or additional data to the page method.

<?= $page->htmlhead([
    // override defaults
    'htmlhead/meta-robots' => function ($kirby, $site, $page) {
        return ['content' => 'noindex']; // do not index this page
    },
    // add new
    'htmlhead/link-feedrss' => function ($kirby, $site, $page) {
        return []; // use defaults of snippet
    },
]) ?>

Site Method: attrLang

There is a language helper available as well.

<html <?= site()->attrLang() ?>>
<!-- ... -->
</html>

Setting

There is only one setting called bnomei.htmlhead.snippets and it takes an array of callbacks. It has sensible defaults but you can add any of the provided snippets or your own snippets. The unittests for this plugin have a more specific example for you to explore.

https://github.com/bnomei/kirby3-htmlhead/blob/master/tests/config/config.php

<?php

return [
    'bnomei.htmlhead.snippets' => [
        /********************************
         * IMPORTANT: order matters!
         */
        'htmlhead/recommended-minimum' => null,
        'htmlhead/title' => function ($kirby, $site, $page) {
            return ['title' => $page->title()];
        },
        'htmlhead/base' => function ($kirby, $site, $page) {
            return ['href' => kirby()->site()->url()];
        },
        'htmlhead/meta-robots' => function ($kirby, $site, $page) {
            return ['content' => 'index, follow, noodp'];
        },
        'htmlhead/meta-author' => function ($kirby, $site, $page) {
            return ['content' => $site->author()];
        },
        'htmlhead/meta-description' => function ($kirby, $site, $page) {
            return ['content' => Str::unhtml($page->seodesc())];
        },
        'htmlhead/link-css' => function ($kirby, $site, $page) {
            return ['files' => ['/assets/app.css']];
        },
        'htmlhead/script-js' => function ($kirby, $site, $page) {
            return ['files' => [
                '/assets/app.js',
                'https://cdn.jsdelivr.net/npm/webfontloader@1.6.28/webfontloader.min.js|sha256-4O4pS1SH31ZqrSO2A/2QJTVjTPqVe+jnYgOWUVr7EEc='
            ]];
        },
        'htmlhead/script-webfontloader' => function ($kirby, $site, $page) {
            return [
                'nonce' => null, // $page->nonce('my-webfontloader-nonce') from https://github.com/bnomei/kirby3-security-headers#setter
                'json' => [
                    'google' => [
                        'families' => ['Montserrat']
                    ],
                ],
            ];
        },
        'htmlhead/link-a11ycss' => function ($kirby, $site, $page) {
            return ['url' => 'https://github.com/ffoodd/a11y.css/blob/master/css/a11y-en_errors-only.css'];
        },
        'htmlhead/link-feedrss' => function ($kirby, $site, $page) {
            // defaults
            return [
                'url' => url('/feed'),
                'title' => $page->title(),
            ];
        },
    ],
    // ... other options
];

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

MIT

It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.