Search Engine Optimization

Introduction

Converge provides a dynamic and intelligent SEO system that automatically generates meta tags for your pages using the page’s front matter data. This allows you to define SEO-related information directly within your markdown files, and Converge will seamlessly transform it into fully optimized meta tags, Open Graph tags, Twitter Cards, and more.

At the heart of this system is the special $frontMatter variable, which exposes all the front matter fields of the current page during SEO configuration. This empowers you to create smart, context-aware metadata that updates automatically as your content changes.

Using `$frontMatter` for Dynamic Meta Tags

The $frontMatter variable represents all front matter fields of the current page, enabling dynamic insertion of values into your meta tags. For example:

Customize page titles like this:
"$frontMatter.title - Converge Framework"
Reference descriptions or nested fields such as $frontMatter.description or $frontMatter.og.type to tailor other metadata dynamically.

This approach makes your SEO setup flexible and automatically tailored to each page, eliminating the need for manual tag updates.

The title meta tag is always available — even if you don’t explicitly define a title in your front matter, Converge falls back to using the page’s filename slug as the title.

Below is an example of the default meta tags generated by Converge for a page named 04-search-engine.md when no custom SEO data is provided:

<title>
   search engine
</title>

<meta property="og:title" content="search engine" />
<meta property="og:type" content="article" />
<meta property="og:description" content="welcome to search engine documentation" />
<meta property="og:image" content="https://convergephp.com/images/converge.png" />

<meta name="twitter:title" content="search engine" />
<meta name="twitter:description" content="welcome to search engine documentation" />
<meta name="twitter:image" content="https://convergephp.com/images/converge.png" />

Cutomizing Tags

You can fully customize the meta tags by using the metaTags() method in your module provider.

customizing title tag

use Converge\Module;
use Converge\Support\Metadata;

public function module(Module $module): Module
{
return $module
    // ...
    ->metaTags(function (Metadata $metadata) {
        $metadata->title("\$frontMatter.title - title");
        // ...
        return $metadata;
    });
}

Customize Open Graph Tags

Use the openGraph() method to specify Open Graph tags for rich previews on social platforms like Facebook and LinkedIn:

use Converge\Module;
use Converge\Support\Metadata;

public function module(Module $module): Module
{
    return $module
        ->metaTags(function (Metadata $metadata) {
            $metadata->openGraph([
                'title' => '$frontMatter.title',
                'type' => '$frontMatter.og.type',
                'description' => '$frontMatter.og.description',
                'url' => url()->current(),
                'image' => 'https://images.unsplash.com/photo-1467232004584-a241de8bcf5d?q=80&w=2069&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
            ]);
            return $metadata;
        });
}

Customize Twitter Cards

Twitter Cards allow you to control how your content appears when shared on Twitter. Define them using twitterCards():

use Converge\Module;
use Converge\Support\Metadata;

public function module(Module $module): Module
{
    return $module
        ->metaTags(function (Metadata $metadata) {
            $metadata->twitterCards([
                'title' => '$frontMatter.title',
                'description' => '$frontMatter.description on x',
                'image' => 'https://images.unsplash.com/photo-1467232004584-a241de8bcf5d?q=80&w=2069&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
            ]);
            return $metadata;
        });
}

Add Custom Meta Tags

You can also define arbitrary custom meta tags (like robots, author, etc.) using addCustom():

use Converge\Module;
use Converge\Support\Metadata;

public function module(Module $module): Module
{
    return $module
        ->metaTags(function (Metadata $metadata) {
            $metadata->addCustom([
                ['name' => 'robots', 'content' => 'index, follow']
            ]);
            return $metadata;
        });
}

the custom tags w'll be like:

<meta name="robots" content="index, follow">

These features give you full control and flexibility over how your documentation pages are indexed and displayed by search engines and social platforms.