Adding a Google Site Ownership Verification File in Metalsmith

Christian Emmer
Christian Emmer
Dec 28, 2019 · 4 min read

In order to manage your website in the Google Search Console you first need to verify ownership of your site. One way of doing this is by downloading a special HTML file from Google and uploading it to your site for Google to crawl.

Here's Google's explanation of Search Console:

Google Search Console is a free service offered by Google that helps you monitor, maintain, and troubleshoot your site's presence in Google Search results. You don't have to sign up for Search Console to be included in Google Search results, but Search Console helps you understand and improve how Google sees your site.

Adding this file in your Metalsmith project is pretty straight forward, but there are a couple of traps.

Project setup

To keep this article short and to the point we're not going to set up a full website, just enough to show sample usage. See "Starting a Metalsmith Project" for a more complete article on how to set up a Metalsmith project.

Starting a Metalsmith Project
Starting a Metalsmith Project
Sep 19, 2019 · 12 min read

Metalsmith is a plugin-based static site generator originally from Segment. It's a current favorite of mine because of how sites are built as a pipeline of plugins where the output of each plugin is the input of the next. This allows for strong control over what happens and when it happens.

Installing packages

Starting with an empty project, install some Metalsmith packages:

npm install --save metalsmith metalsmith-ignore metalsmith-include-files

Source file structure

Create the following directories and files for use in the build pipeline:

├── index.js
└── src
    ├── google0123456789abcdef.html
    └── index.html

For now we're pretending google0123456789abcdef.html is the file you downloaded from Google which is unique for every domain + user combo. Follow the instructions here on how to find and download your own file.

Writing the source files

Set up your index.js file like this:

const Metalsmith = require('metalsmith');
const ignore     = require('metalsmith-ignore');
const include    = require('metalsmith-include-files');

    .source('./src')         // source directory for the pipeline
    .use(ignore([            // ignore any processed HTML
    .use(include({           // include the raw HTML file
        '': ['./src/google*.html']
    .destination('./build')  // destination directory of the pipeline
    .clean(true)             // clean the destination directory before build
    .build(function (err) {  // execute the build
        if (err) {
            throw err;

This will:

  • Copy src/index.html to build/index.html.
  • Copy src/google0123456789abcdef.html to build/google0123456789abcdef.html, ignoring any other pipeline processing.

Then fill in your src/index.html with some dummy content:

<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8">
    <title>Lorem Ipsum</title>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

And src/google0123456789abcdef.html with the content:

google-site-verification: google0123456789abcdef.html


Run the build command like normal:

node index

And you should see build/google0123456789abcdef.html exist with the exact same content as src/google0123456789abcdef.html.

Why the extra plugins?

Google requires the uploaded verification file to be an exact copy of the one downloaded, even extra line endings could make it fail verification. It's likely your Metalsmith build pipeline is a lot more complicated than the example above, and you're probably using at least one plugin that modifies the path or contents of HTML files. Because of that, these steps to include the verification file should be as close to the end of the pipeline as possible.

For example, if you use metalsmith-permalinks like:

    relative: false

you'll end up with the file at build/google0123456789abcdef/index.html, but we need the file in the root of the output directory.

Or if you use metalsmith-layouts like:

    pattern: '**/*.html',
    default: 'page.hbs',
    engine: 'handlebars'

it will process src/google0123456789abcdef.html through that default template and the content will no longer match.

Other dangers

Because the verification file isn't meaningful to site viewers or non-Google crawlers you probably don't want to link to it from any of your other pages.

If you're using metalsmith-sitemap to generate a sitemap you probably want to do it in between the metalsmith-ignore and metalsmith-include-files steps so the verification file doesn't get referenced in the sitemap.

If you're using metalsmith-formatcheck to lint your output HTML (see "Linting Metalsmith Output HTML") you're going to want to do that before including the verification file as it isn't valid HTML.

Linting Metalsmith Output HTML
Linting Metalsmith Output HTML
Dec 8, 2019 · 3 min read

Best I know, there aren't any good ways to test the output of a Metalsmith build to make sure things like updated dependencies didn't break styling or content. But one thing we can do is lint the output HTML to make sure it's at least syntactically correct and doesn't contain broken links.