199 lines
7.8 KiB
Markdown
199 lines
7.8 KiB
Markdown
---
|
|
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.
|
|
|
|
```yaml
|
|
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](#generate-a-list-of-children-articles).
|
|
|
|
##### `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.
|
|
|
|
```yaml
|
|
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](#latest-links)._
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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](#cascade) to add the same content to
|
|
all children pages as well.
|
|
|
|
```yaml
|
|
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](https://gohugo.io/content-management/front-matter/#front-matter-cascade)
|
|
built in into Hugo.
|
|
|
|
```yaml
|
|
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](#show-in) and [hide-in](#hide-in).
|
|
|