SEO and social sharing

Give each page a useful title and description, then configure the public origin before publishing. Monoline generates metadata from these settings; search engines decide whether and how to display your pages.

Configure the publishing URL

In monoline-docs.yml:

title: Team handbook
description: Guides and API reference for the Example SDK.
site: https://docs.example.com
base: /
indexing: true
assetsDirectory: ./assets
seo:
  titleTemplate: "%s | Team handbook"
  socialImage: /assets/social.png
  socialImageAlt: Example SDK documentation
  author:
    type: Person
    name: Alex Example
    url: https://example.com/about
  publisher:
    type: Organization
    name: Example SDK
    url: https://example.com

site is an HTTP(S) origin without a path, query or fragment. For documentation at https://example.com/handbook/, use site: https://example.com and base: /handbook/. The base applies to canonical URLs, sitemap entries and local social image URLs. See Deployment for the corresponding host layout.

titleTemplate must contain %s, replaced with the page’s seoTitle or title. Its default is %s | followed by the configured site title. Keep the result descriptive and avoid repeating the site name in seoTitle.

socialImage requires site and a local PNG, JPEG or WebP file under assetsDirectory. The example uses assets/social.png. Monoline emits an absolute image URL for Open Graph and Twitter sharing metadata. socialImageAlt provides a meaningful image description; it defaults to the site title.

author and publisher are optional identity objects with type (Person or Organization), name, and optional HTTP(S) url and sameAs profile URLs. Use the actual content author and publishing identity. Publisher information is attached to the website and pages; author information is attached to pages. Do not use product websites as alternate personal identities.

Write page metadata

---
title: Install the SDK
navTitle: Installation
seoTitle: Install the Example SDK
description: Install the Example SDK, configure your API key and send your first request.
updatedAt: 2026-10-01
---

Use descriptions that explain what readers can accomplish on that particular page. Update updatedAt when the content changes; it is not automatically derived from Git. See Frontmatter for the full reference.

Control previews and unpublished content

Build a hosted staging site with:

npx monoline-docs build --indexing false

This production build excludes drafts and adds noindex, nofollow to pages. It omits the sitemap, generated robots file and structured data. Set indexing: false in configuration when that is the default for your environment.

Use draft: true for unfinished pages: production builds omit them entirely. The local development preview includes drafts and marks pages as noindex. Keep draft routes out of production navigation and links.

Use noindex: true for a published page that should be excluded from discovery. Its HTML remains accessible. These settings are not access controls; protect private material at the host. Google must be able to crawl a page to read its noindex directive.

Check generated output

Run npm run build and inspect the configured output directory before deploying:

• Page HTML contains the expected title, description, canonical URL and sharing metadata.
• Indexable pages with site configured contain WebSite JSON-LD. The homepage uses WebPage; other pages use Article, or TechArticle with layout: reference. Non-home pages also contain BreadcrumbList data from navigation.
• sitemap.xml contains production routes with the configured origin and base, excluding drafts and noindex pages. Authored updatedAt supplies lastmod; pages without that date omit it. Do not substitute the build date.
• With base: /, robots.txt allows crawling and points to the sitemap. With a subpath, Monoline omits this file: the origin owner manages /robots.txt and can add Sitemap: https://example.com/handbook/sitemap.xml there.
• The generated 404.html is noindex. Configure the host to serve it with an HTTP 404 status for missing pages.

Without site, Monoline emits no canonical URLs, sitemap, robots file or site/page/breadcrumb JSON-LD. Titles and descriptions still render. No production origin is inferred. With indexing disabled, canonical URLs still use site when set.

Troubleshoot metadata

Connect Google Search Console

After deploying your production build:

1. Add and verify a Search Console property. Use a Domain property when you control DNS, or a URL-prefix property matching the published docs URL, including its subpath.
2. Submit the deployed sitemap.xml URL in the Sitemaps report. For the subpath example, submit https://example.com/handbook/sitemap.xml.
3. Inspect the homepage and a representative guide with URL Inspection. Check crawl access, indexing status and the canonical selected by Google.
4. Review the Page indexing report for unexpected exclusions and the Performance report for search queries and pages after data becomes available.

A submitted sitemap helps discovery; it does not guarantee indexing or rankings. Structured data describes the content and does not guarantee a rich result.