Keywords

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the keywords element to provide additional terms from an uncontrolled vocabulary to assist search systems. Keywords should be written in a comma-separated list.

Notes

The keywords element contains text.
The keywords element can occur in any info element.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The keywords element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Add keywords for common search terms to a page on connecting to Wifi:

<page xmlns="http://projectmallard.org/1.0/" id="wifi">
  <info>
    <keywords>wireless, internet, wep, wpa, wpa2</keywords>
  </info>
  <title>Connect to WiFi</title>
</page>

Processing Expectations

Processing tools with search integration should use the keywords for a page to inform the search results. Ideally, keywords should be used for searching even when only searching on metadata like titles and descs, as well as for full-text search.

Processing tools may also use keywords from sections and block elements, but these may be limited to full-text search only.

Processing tools should expect that keywords are formatted as a comma-separated list, as some keywords may be multi-word terms. However, since there is no expectation to do any sort of structured analysis, even a space-separated list should provide data for search.

If processing tools are generating HTML and relying on external search providers, they should copy the page keywords into the content attribute of a meta element with the name attribute set to keywords. Note that search engines don't place much importance on keywords provided in this way.

As with other informational elements, there is no expectation that keywords will be displayed to users directly.

Comparison to Other Formats

DocBook provides the keywordset element for keywords. The keywordset element contains any number of keyword elements, rather than a comma-separated list.

DITA provides the keywords element for keywords. The keywords element contains any number of keyword elements, rather than a comma-separated list.

HTML uses the meta element with the name attribute set to keywords. The keywords are lists in the content attribute. The keywords are a comma-separated list.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the keywords element. The namespace declarations for this definition are on the page Pages.

mal_info_keywords = element keywords {
  mal_info_keywords_attr,
  mal_info_keywords_inline
}
mal_info_keywords_attr = (
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_info_keywords_inline = text ?