Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/.github/instructions/frontmatter-reference.instr...

7.8 KiB
Raw Permalink Blame History

applyTo
content/**/*.md, layouts/**/*.html

Complete Frontmatter Reference

Every documentation page includes frontmatter which specifies information about the page. Frontmatter populates variables in page templates and the site's navigation menu.

title: # Title of the page used in the page's h1
seotitle: # Page title used in the html <head> title and used in search engine results
list_title: # Title used in article lists generated using the {{< children >}} shortcode
description: # Page description displayed in search engine results
menu:
  influxdb_2_0:
    name: # Article name that only appears in the left nav
    parent: # Specifies a parent group and nests navigation items
weight: # Determines sort order in both the nav tree and in article lists
draft: # If true, will not render page on build
product/v2.x/tags: # Tags specific to each version (replace product and .x" with the appropriate product and minor version )
related: # Creates links to specific internal and external content at the bottom of the page
  - /path/to/related/article
  - https://external-link.com, This is an external link
external_url: # Used in children shortcode type="list" for page links that are external
list_image: # Image included with article descriptions in children type="articles" shortcode
list_note: # Used in children shortcode type="list" to add a small note next to listed links
list_code_example: # Code example included with article descriptions in children type="articles" shortcode
list_query_example:# Code examples included with article descriptions in children type="articles" shortcode,
  # References to examples in data/query_examples
canonical: # Path to canonical page, overrides auto-gen'd canonical URL
v2: # Path to v2 equivalent page
alt_links: # Alternate pages in other products/versions for cross-product navigation
  cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/
  core: /influxdb3/core/path/to/page/
prepend: # Prepend markdown content to an article (especially powerful with cascade)
  block: # (Optional) Wrap content in a block style (note, warn, cloud)
  content: # Content to prepend to article
append: # Append markdown content to an article (especially powerful with cascade)
  block: # (Optional) Wrap content in a block style (note, warn, cloud)
  content: # Content to append to article
metadata: [] # List of metadata messages to include under the page h1
updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata)
source: # Specify a file to pull page content from (typically in /content/shared/)

Title usage

title

The title frontmatter populates each page's HTML h1 heading tag. It shouldn't be overly long, but should set the context for users coming from outside sources.

seotitle

The seotitle frontmatter populates each page's HTML title attribute. Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized.

list_title

The list_title frontmatter determines an article title when in a list generated by the {{< children >}} shortcode.

menu > name

The name attribute under the menu frontmatter determines the text used in each page's link in the site navigation. It should be short and assume the context of its parent if it has one.

Page Weights

To ensure pages are sorted both by weight and their depth in the directory structure, pages should be weighted in "levels." All top level pages are weighted 1-99. The next level is 101-199. Then 201-299 and so on.

Note: _index.md files should be weighted one level up from the other .md files in the same directory.

Related content

Use the related frontmatter to include links to specific articles at the bottom of an article.

  • If the page exists inside of this documentation, just include the path to the page. It will automatically detect the title of the page.
  • If the page exists inside of this documentation, but you want to customize the link text, include the path to the page followed by a comma, and then the custom link text. The path and custom text must be in that order and separated by a comma and a space.
  • If the page exists outside of this documentation, include the full URL and a title for the link. The link and title must be in that order and separated by a comma and a space.
related:
  - /v2.0/write-data/quick-start
  - /v2.0/write-data/quick-start, This is custom text for an internal link
  - https://influxdata.com, This is an external link

Canonical URLs

Search engines use canonical URLs to accurately rank pages with similar or identical content. The canonical HTML meta tag identifies which page should be used as the source of truth.

By default, canonical URLs are automatically generated for each page in the InfluxData documentation using the latest version of the current product and the current path.

Use the canonical frontmatter to override the auto-generated canonical URL.

Note: The canonical frontmatter supports the {{< latest >}} shortcode.

canonical: /path/to/canonical/doc/

# OR

canonical: /{{< latest "influxdb" "v2" >}}/path/to/canonical/doc/

v2 equivalent documentation

To display a notice on a 1.x page that links to an equivalent 2.0 page, add the following frontmatter to the 1.x page:

v2: /influxdb/v2.0/get-started/

Alternative links for cross-product navigation

Use the alt_links frontmatter to specify equivalent pages in other InfluxDB products, for example, when a page exists at a different path in a different version or if the feature doesn't exist in that product. This enables the product switcher to navigate users to the corresponding page when they switch between products. If a page doesn't exist in another product (for example, an Enterprise-only feature), point to the nearest parent page if relevant.

alt_links:
  cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/
  cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/
  core: /influxdb3/core/reference/cli/influxdb3/update/  # Points to parent if exact page doesn't exist

Supported product keys for InfluxDB 3:

  • core
  • enterprise
  • cloud-serverless
  • cloud-dedicated
  • clustered

Prepend and append content to a page

Use the prepend and append frontmatter to add content to the top or bottom of a page. Each has the following fields:

append: |
  > [!Note]
  > #### This is example markdown content
  > This is just an example note block that gets appended to the article.

Use this frontmatter with cascade to add the same content to all children pages as well.

cascade:
  append: |
    > [!Note]
    > #### This is example markdown content
    > This is just an example note block that gets appended to the article.

Cascade

To automatically apply frontmatter to a page and all of its children, use the cascade frontmatter built in into Hugo.

title: Example page
description: Example description
cascade:
  layout: custom-layout

cascade applies the frontmatter to all children unless the child already includes those frontmatter keys. Frontmatter defined on the page overrides frontmatter "cascaded" from a parent.

Use shared content in a page

Use the source frontmatter to specify a shared file to use to populate the page content. Shared files are typically stored in the /content/shared directory.

When building shared content, use the show-in and hide-in shortcodes to show or hide blocks of content based on the current InfluxDB product/version. For more information, see show-in and hide-in.