Titles, descriptions, sitemap and share cards

What the head contains by default

The head of a page is built from the document, the version being read and the page. Anything you set in SEO Tags or in the record's stored structured data wins over these defaults.

Part	On a document's front page	On a page
Title	The document's name	The page's title
Description	The document's description	The start of the page's text, at most 160 characters, cut with an ellipsis
Type	`article`	`article`
Language	The document's language	The document's language
Canonical address	The document's own address when it has one, else its address in its own language under the documentation's path	The page's address under the document's own address when it has one, else the address asked
Structured data	A `TechArticle` and a `BreadcrumbList`	A `TechArticle` and a `BreadcrumbList`
Robots	The document's own robots meta	The page's, else the document's

The BreadcrumbList runs from Documentation to the document to the page. The TechArticle has these keys:

Key	Holds
`headline`, `description`	The title and the description above. A description stored in SEO Tags replaces the default.
`image`	The record's share image, once it is drawn, or the `og:image` stored in SEO Tags.
`datePublished`	As an ISO 8601 date. For a page, the date its version was published, else the date the page was created. For a front page, the date the document was created.
`dateModified`	As an ISO 8601 date. For a page, when its text or one of its notes last changed. For a front page, when the document last changed.
`version`	The version number being read.
`inLanguage`	The document's language, such as `en`.
`mainEntityOfPage`	The canonical address.
`author`	A `Person`, when a meta tag named `author` names one on the page, else on the document. Left out when neither does.
`publisher`	The site as an `Organization`, with the site.title setting as its name and the site.logo setting as its logo. Left out when the site has no title.

A record whose robots meta says noindex or none has no TechArticle. JSON-LD stored on the record replaces the TechArticle, and the BreadcrumbList stays. A document has a Schema (JSON) field for it.

Languages in the head

A document and its pages each have one language, and the head says which. inLanguage in the TechArticle is the document's language. og:locale is the same language as Open Graph writes a locale, such as en_US or fa_IR.

When the document, or the page, has two or more editions, the head also carries these tags:

a rel="alternate" link with hreflang for each edition, at that edition's own address;
one hreflang="x-default" link, at the edition in the site's first language, when there is one;
an og:locale:alternate tag for each edition besides the one being read.

They come from the list the header's language switcher shows. On a document's front page that is each edition of the document. On a page it is each edition that has the page, and an edition without it is not listed. Search engines read the head as a guest, so an edition locked to permissions is not listed. See The translations entry and Languages and language editions.

Override a part with SEO Tags

Both a document and a page have an SEO Tags field. Each row has a Tag, which is title, meta or link, its Attributes as JSON, and its Content. A title replaces the page's title. A meta or link tag replaces the default tag with the same name. The Mishka Chelekom documentation sets every page's head this way, with a title row and a description row:

Tag	Attributes	Content
title	`{}`	The head title of the page
meta	`{"name": "description"}`	The meta description

A value may name a variable. The head fills them in for the page being read:

Variable	Value
`{{doc.title}}`	The page's title, or the document's name on its front page
`{{doc.description}}`	The description of the page or the document
`{{doc.url}}`	The canonical address
`{{doc.version}}`	The version number being read
`{{doc.group}}`	The title of the nearest group the page is filed under
`{{doc.published_at}}`	When the page was published, as an ISO 8601 date
`{{doc.modified_at}}`	When it last changed
`{{workspace.name}}`	The document's name
`{{workspace.description}}`	The document's description
`{{workspace.url}}`	The document's address

For example, a title tag with the content {{doc.title}} - {{workspace.name}} gives each page of a document a title of its own name followed by the document's.

The sitemap

The documentation adds itself to the site's /sitemap.xml. Each active document is listed at its front page, and each approved page of the version a reader is shown at its own address, in the document's language. The sitemap leaves out:

a draft document and a page still in review;
the pages of older versions that only ?v= reaches;
a document or a page locked to permissions, because the sitemap reads as a visitor who is not signed in;
a document whose robots meta says noindex or none, with all its pages that hold no robots meta of their own, and a single page whose own robots meta says so.

A document with no published version still draws its front page, and the sitemap lists that page alone. Writing a document, a version or a page rebuilds the site's sitemap. An address is listed only while the site serves a page at that path.

Share cards

A share card is the image a link shows when it is shared, drawn at 1200 by 630 pixels. The documentation draws one for the front page of every active document and for every approved page of a published version of an active document. A group with no page of its own has none, because it is only a heading. A version's front page has none of its own: it is drawn at the document's address and uses the document's card. A page of an older version, reached with ?v=, has a card of its own that shows its version.

A card shows these:

the title and the description of the record;
a label above the title: the word Documentation on a front page, or the document's name above a page, with the group the page is filed under after it when it is under one;
the version, such as Version 1.2.0, which on a front page is the version a reader lands on;
the site's name and address, and its site.logo setting as the logo.

The card is drawn in the background after you save, and again only when what it shows has changed. A document needs to be active. A page needs both reviews approved, a published version and an active document. A record locked to permissions has no card, and neither has a record whose SEO Tags store an og:image of their own, because that image is shown instead.

The Share image field of a saved document or page shows the card as drawn and has a Regenerate button that draws it again. To draw every card of the site again, use Redraw in the dialog described in Set up documents on a site. It covers the cards a visitor who is not signed in can reach: each active document's front page and each approved page, for every published version, in the languages the site lists.