A next-generation tool to create blazing-fast documentation sites
API
created:11/5/2020
,
updated:12/6/2020

Search engine optimization <meta>, opengraph, and twitter card tags are inserted in the <head /> section of the pages generated by component-controls.

Site-level SEO

The site SEO is configured in your runtime configuration file. The site meta settings are used both for SEO purposes as page <meta /> tags and displayed in the application user interface tags.

example:

.config/runtime.ts

import { RunOnlyConfiguration } from "@component-controls/core";
const config: RunOnlyConfiguration = {
analytics: 'UA-172446254-1',
title: `My custom title`,
description: `Amazing react UI library`,
language: `en`,
author: `@twitter_account`,
}
export default config;

title

The site title is used as part of the page title in the format %s | title. The default value is Component controls.

description

The site description is used as a fallback page description if no story or document description is specified. The default value is Component controls stories. Write your components documentation with MDX and JSX. Design, develop, test, and review in a single site..

image

The site image is used as a fallback page image if no document image is specified.

siteUrl

The siteUrl is used as the base url if the image property is specified as a relative path.

author

The site author is used as a fallback twitter card author if no document author is specified. The default value is @component-controls.

language

The site language is used as a <html lang={language} /> tag in the header. The default value is en.

The links meta tag specifies the favicons for the site and component-controls comes with a set of default favicons that you can import in your configuration file.

.config/runtime.ts

import { RunOnlyConfiguration } from "@component-controls/core";
import { defaultLinks } from "@component-controls/app";
const config: RunOnlyConfiguration = {
title: `My custom title`,
links: [...defaultLinks, {
rel: 'shortcut icon',
href: '/static/favicon.ico'
}]
}
export default config;

Page-level SEO

The page SEO is configured in your MDX or ESM document files.

example:

document.mdx

---
title: Getting started/SEO
author: atanasster
type: tutorial
order: 6
route: /tutorial/getting-started/seo
tags:
- configuration
- SEO
keywords:
- search engine optimization
- SEO
image: /static/my-custom-image.jpg
---
// the following will copy the image to the static folder
import myImg from './media/my-custom-image.jpg';

title

The last segment of the document title is used for the page title and the opengraph/twitter card titles.

description

The story or document description is used for the description tags and the image:alt tag if an image is configured for the document.

image

The document image can be an absolute path to an image or a relative path that will be concatenated with the siteUrl.

author

The document image will be used as the twitter card author.

keywords / tags

The list of keywords meta tag. If the keywords field is not specified, will use the tags document property.

Append meta

You can use the Helmet component to add any custom tags to the <head > section of the site

.config/runtime.ts

import { RunOnlyConfiguration } from "@component-controls/core";
import { Helmet } from "@component-controls/gatsby-theme-stories";
//or import { Helmet } from "@component-controls/nextjs-plugin";
const config: RunOnlyConfiguration = {
title: `My custom title`,
app: app: ({ children }) => (
<div>
<Helmet>
<meta name="description" content="a page with custom meta description" />
</Helmet>
{children}
</div>
),
}
export default config;

Replace seo meta

you can even completely replace the default seo meta tags:

.config/runtime.ts

import { RunOnlyConfiguration } from "@component-controls/core";
import { Helmet } from "@component-controls/gatsby-theme-stories";
//or import { Helmet } from "@component-controls/nextjs-plugin";
const config: RunOnlyConfiguration = {
title: `My custom title`,
seo: (
<Helmet>
<meta name="description" content="a page with custom seo meta tags" />
</Helmet>
),
}
export default config;