bnomei/kirby3-htmlhead

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

Installs: 154

Dependents: 0

Suggesters: 0

Stars: 3

Watchers: 0

Forks: 1

Open Issues: 2

Type:kirby-plugin

1.7.6 2019-03-11 10:11 UTC

README

GitHub release License Kirby Version Kirby 3 Pluginkit

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

Key Features

  • basic metatags
  • js and css
  • rss feed (xml)
  • opengraph
  • webfontloader to load and track webfonts
  • loadjs to load js and css
  • a11y.css when config debug => true
  • Unregistered Snippet examples for google-analytics and google-tag-manager. You need to copy them to your /site/snippets folder.

Usage

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

<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() ?>'">'
<link rel="canonical" href="<?= $page->url() ?>">'
<title><?= $page->title() ?></title>
<?= $page->htmlhead_snippets() ?>

Or if you would use these meta tags anyway you can use

<?= $page->htmlhead_alpha($page->title()) ?>
<?= $page->htmlhead_snippets() ?>
// or just
<?php snippet('plugin-htmlhead') ?>

You can also provide custom metatags and on-the-fly options.

<?php
    $metatags = [
        '<meta name="robots" content="noindex, nofollow">',
        '<meta name="keywords" content="Kirby,Plugin,Html,Head,Meta,Snippets">',
    ];
    $options = [
        'htmlhead/seo' => false,
        'htmlhead/opengraph' => false,
    ]
?>
<?= $page->htmlhead_alpha($page->title(), $metatags) ?>
<?= $page->htmlhead_snippets($options) ?>
// or just
<?php snippet('plugin-htmlhead', [
    'metatags' => $metatags, 
    'options' => $options
]) ?>

There is a language helper available as well.

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

Extending with Snippets

If you have your own snippets you want to have called at the header simply add them to the bnomei.htmlhead.snippets setting. For example you could create a snippet/matomo.php with your piwik/matomo tracking code and just add that to the config.

return [
    'bnomei.htmlhead.snippets' => [
        'matomo'
    ],
    // ... other options
];

Setting

You can set these in your site/config/config.php or in your template code since $page has to exist.

bnomei.htmlhead.snippets

  • default: []
  • this will call all snippets of this plugin. add the name of your snippet without its file-extension.

bnomei.htmlhead.seo (template only)

Example: site/plugins/ogtags/index.php

<?php
Kirby::plugin('myname/ogtags', [
    'pageMethods' => [
        'head_author' => function () {
            return site()->author()->isNotEmpty() ? site()->author()->value() : null;
        },
        'head_description' => function () {
            return $this->description()->isNotEmpty() ? $this->description()->value() : site()->description()->value();
        },
        'head_image' => function () {
            return $this->seoimage()->isNotEmpty() ? $this->seoimage()->toFile() : $this->images()->first();
        },
    ]
]);

bnomei.htmlhead.opengraph (template only)

  • default: see snippet, false to disable

bnomei.htmlhead.css

  • default: []
  • array of css files URIs

TIP: use | to add SRI to external stylesheets. example: https://www.external.com/stylesheet.css|sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC

bnomei.htmlhead.js

  • default: []
  • array of js files URIs

TIP: use | to add SRI to external scripts.

bnomei.htmlhead.feed

  • default: false
  • URI for application/rss+xml feed page object.

bnomei.htmlhead.a11ycss.debugOnly

  • default: option('debug', false)
  • a11y.css will only be loaded if debug is enabled.

bnomei.htmlhead.a11ycss

bnomei.htmlhead.loadjs

TIP: if loading assets from other servers consider using fingerprint plugin with SRI instead.

return [
    'bnomei.htmlhead.loadjs' => [
        'home' => [ // custom id
            'template' => ['home', 'projects'], // templates
            'dependencies' => [
                '/assets/js/zepto.min.js',
                '/assets/js/flickty.pkg.min.js',
                '/assets/css/flickty.min.css', // css too!
                '/assets/js/complex-stuff.js'
            ]
        ],
        '*' => [ // fallback
            'template' => [], // all templates
            'dependencies' => [
                '/assets/js/zepto.min.js',
                '/assets/js/simple.js'
            ]
        ],
    ],
    // ... other options
];

bnomei.htmlhead.webfontloader

  • default: false
  • set a string to be echoed example
return [
    'bnomei.htmlhead.webfontloader' => 
        "google: {
            families: ['Droid Sans']
        },
        custom: {
            families: ['My Font', 'My Other Font:n4,i4,n7'],
            urls: ['/fonts.css']
        }",
    // ... other options
];

bnomei.htmlhead.lang

  • default: 'en' as fallback in non multilang setups

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.