2018-12-13 18:47:02 +00:00
# Contributing to InfluxData Documentation
2019-01-09 23:08:51 +00:00
## Sign the InfluxData CLA
The InfluxData Contributor License Agreement (CLA) is part of the legal framework
for the open-source ecosystem that protects both you and InfluxData.
2019-10-07 17:22:54 +00:00
To make substantial contributions to InfluxData documentation, first sign the InfluxData CLA.
What constitutes a "substantial" change is at the discretion of InfluxData documentation maintainers.
2019-01-09 23:08:51 +00:00
2019-10-07 17:28:48 +00:00
[Sign the InfluxData CLA ](https://www.influxdata.com/legal/cla/ )
2019-01-09 23:08:51 +00:00
2019-10-07 17:22:54 +00:00
_**Note:** Typo and broken link fixes are greatly appreciated and do not require signing the CLA._
2020-09-25 22:00:24 +00:00
*If it's your first time contributing and you're looking for an easy update, check out our [good-first-issues ](https://github.com/influxdata/docs-v2/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue )!*
2020-09-25 21:55:06 +00:00
2019-01-09 23:08:51 +00:00
## Make suggested updates
### Fork and clone InfluxData Documentation Repository
[Fork this repository ](https://help.github.com/articles/fork-a-repo/ ) and
[clone it ](https://help.github.com/articles/cloning-a-repository/ ) to your local machine.
### Run the documentation locally (optional)
To run the documentation locally, follow the instructions provided in the README.
### Make your changes
Make your suggested changes being sure to follow the [style and formatting guidelines ](#style--formatting ) outline below.
### Submit a pull request
Push your changes up to your forked repository, then [create a new pull request ](https://help.github.com/articles/creating-a-pull-request/ ).
## Style & Formatting
### Markdown
All of our documentation is written in [Markdown ](https://en.wikipedia.org/wiki/Markdown ).
### Semantic Linefeeds
Use [semantic linefeeds ](http://rhodesmill.org/brandon/2012/one-sentence-per-line/ ).
Separating each sentence with a new line makes it easy to parse diffs with the human eye.
**Diff without semantic linefeeds:**
``` diff
2019-02-25 22:42:04 +00:00
-Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB.
+Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB.
2019-01-09 23:08:51 +00:00
```
**Diff with semantic linefeeds:**
``` diff
2019-02-25 22:33:02 +00:00
Data is taking off.
2019-02-25 22:42:04 +00:00
This data is time series.
2019-01-09 23:08:51 +00:00
You need a database that specializes in time series.
-You should check out InfluxDB.
+You need InfluxDB.
```
2020-12-23 20:54:08 +00:00
### Article headings
Use only h2-h6 headings in markdown content.
h1 headings act as the page title and are populated automatically from the `title` frontmatter.
h2-h6 headings act as section headings.
### Image naming conventions
Save images using the following naming format: `project/version-context-description.png` .
For example, `influxdb/2-0-visualizations-line-graph.png` or `influxdb/2-0-tasks-add-new.png` .
Specify a version other than 2.0 only if the image is specific to that version.
## Page frontmatter
2019-01-09 23:08:51 +00:00
Every documentation page includes frontmatter which specifies information about the page.
Frontmatter populates variables in page templates and the site's navigation menu.
```yaml
2019-02-20 21:55:01 +00:00
title: # Title of the page used in the page's h1
2019-01-09 23:08:51 +00:00
seotitle: # Page title used in the html < head > title and used in search engine results
2019-03-25 16:25:01 +00:00
list_title: # Title used in article lists generated using the {{< children > }} shortcode
2019-01-09 23:08:51 +00:00
description: # Page description displayed in search engine results
menu:
2020-07-28 22:34:16 +00:00
influxdb_2_0:
2019-01-09 23:08:51 +00:00
name: # Article name that only appears in the left nav
parent: # Specifies a parent group and nests navigation items
2019-05-15 14:06:30 +00:00
weight: # Determines sort order in both the nav tree and in article lists
2019-01-09 23:08:51 +00:00
draft: # If true, will not render page on build
2020-12-23 20:54:08 +00:00
product/v2.x/tags: # Tags specific to each version (replace product and .x" with the appropriate product and minor version )
2019-05-15 14:06:30 +00:00
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
2020-03-11 17:04:32 +00:00
external_url: # Used in children shortcode type="list" for page links that are external
2020-03-11 17:21:49 +00:00
list_image: # Image included with article descriptions in children type="articles" shortcode
2020-03-11 17:04:32 +00:00
list_note: # Used in children shortcode type="list" to add a small note next to listed links
2020-03-20 17:01:37 +00:00
list_code_example: # Code example included with article descriptions in children type="articles" shortcode
2020-04-27 16:53:27 +00:00
list_query_example: # Code examples included with article descriptions in children type="articles" shortcode,
# References to examples in data/query_examples
2020-09-08 21:34:48 +00:00
canonical: # Path to canonical page, overrides auto-gen'd canonical URL
2020-09-11 21:18:18 +00:00
v2: # Path to v2 equivalent page
2021-04-09 21:57:27 +00:00
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
2019-01-09 23:08:51 +00:00
```
2020-12-23 20:54:08 +00:00
### Title usage
2019-01-09 23:08:51 +00:00
##### `title`
The `title` frontmatter populates each page's h1 header.
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.
2019-03-25 16:25:01 +00:00
##### `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 ).
2019-01-09 23:08:51 +00:00
##### `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.
2019-02-06 17:48:09 +00:00
#### 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._
2020-12-23 20:54:08 +00:00
### 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/
```
2021-04-09 21:57:27 +00:00
### v2 equivalent documentation
2020-12-23 20:54:08 +00:00
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/
```
2021-04-09 21:57:27 +00:00
### 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:
- **block:** _(Optional)_ block style to wrap content in (note, warn, cloud, or enterprise)
- **content:** _**(Required)**_ markdown content to add.
```yaml
append:
block: note
content: |
#### 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:
block: note
content: |
#### This is example markdown content
This is just an example note block that gets appended to the article.
```
2020-12-23 20:54:08 +00:00
### 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
2021-04-09 21:57:27 +00:00
those frontmatter keys. Frontmatter defined on the page overrides frontmatter
2020-12-23 20:54:08 +00:00
"cascaded" from a parent.
## Shortcodes
2019-01-09 23:08:51 +00:00
### Notes and warnings
Shortcodes are available for formatting notes and warnings in each article:
```md
{{% note %}}
Insert note markdown content here.
{{% /note %}}
{{% warn %}}
Insert warning markdown content here.
{{% /warn %}}
```
### Enterprise Content
2020-04-22 17:05:44 +00:00
For sections content that relate specifically to InfluxDB Enterprise, use the `{{% enterprise %}}` shortcode.
2019-01-09 23:08:51 +00:00
```md
{{% enterprise %}}
Insert enterprise-specific markdown content here.
{{% /enterprise %}}
```
2019-03-13 19:59:46 +00:00
#### Enterprise name
The name used to refer to InfluxData's enterprise offering is subject to change.
2019-03-27 15:17:23 +00:00
To facilitate easy updates in the future, use the `enterprise-name` shortcode
when referencing the enterprise product.
This shortcode accepts a `"short"` parameter which uses the "short-name".
2019-03-13 19:59:46 +00:00
```
This is content that references {{< enterprise-name > }}.
2019-03-27 15:17:23 +00:00
This is content that references {{< enterprise-name " short " > }}.
2019-03-13 19:59:46 +00:00
```
2019-03-27 15:17:23 +00:00
Product names are stored in `data/products.yml` .
#### Enterprise link
References to InfluxDB Enterprise are often accompanied with a link to a page where
visitors can get more information about the Enterprise offering.
This link is subject to change.
Use the `enterprise-link` shortcode when including links to more information about
InfluxDB Enterprise.
```
Find more info [here][{{< enterprise-link > }}]
```
2019-03-13 19:59:46 +00:00
2019-03-27 14:24:20 +00:00
### InfluxDB Cloud Content
2021-07-07 16:53:54 +00:00
For sections of content that relate specifically to InfluxDB Cloud, use the `{{% cloud %}}` shortcode.
2019-03-13 19:59:46 +00:00
```md
{{% cloud %}}
2020-04-22 17:05:44 +00:00
Insert cloud-specific markdown content here.
2019-03-13 19:59:46 +00:00
{{% /cloud %}}
```
2019-03-27 14:24:20 +00:00
#### InfluxDB Cloud name
2019-03-13 19:59:46 +00:00
The name used to refer to InfluxData's cloud offering is subject to change.
2019-03-27 15:17:23 +00:00
To facilitate easy updates in the future, use the `cloud-name` short-code when
referencing the cloud product.
This shortcode accepts a `"short"` parameter which uses the "short-name".
2019-03-13 19:59:46 +00:00
```
This is content that references {{< cloud-name > }}.
2019-03-27 15:17:23 +00:00
This is content that references {{< cloud-name " short " > }}.
2019-03-13 19:59:46 +00:00
```
2019-03-27 15:17:23 +00:00
Product names are stored in `data/products.yml` .
#### InfluxDB Cloud link
References to InfluxDB Cloud are often accompanied with a link to a page where
visitors can get more information.
This link is subject to change.
Use the `cloud-link` shortcode when including links to more information about
InfluxDB Cloud.
```
Find more info [here][{{< cloud-link > }}]
```
2019-03-13 19:59:46 +00:00
2020-08-19 19:53:38 +00:00
### Latest links
Each of the InfluxData projects have different "latest" versions.
Use the `{{< latest >}}` shortcode to populate link paths with the latest version
for the specified project.
```md
[Link to latest Telegraf ](/{{< latest "telegraf" >}}/path/to/doc/ )
```
2020-08-19 20:46:54 +00:00
To constrain the latest link to a major version, include a second argument with
the major version:
```md
[Link to latest InfluxDB 1.x ](/{{< latest "influxdb" "v1" >}}/path/to/doc/ )]
```
2020-08-19 19:53:38 +00:00
`{{< latest "telegraf" >}}` is replaced with `telegraf/v1.15` (or whatever the latest version is).
2020-08-19 20:46:54 +00:00
`{{< latest "influxdb" "v1" >}}` is replaced with `influxdb/v1.8` (or whatever the latest v1.x version is).
2020-08-19 19:53:38 +00:00
Use the following for project names:
- influxdb
- telegraf
- chronograf
- kapacitor
- enterprise_influxdb
**Note**: Include a leading slash before the latest shortcode and a trailing slash after in all link paths:
```md
2020-08-19 20:46:54 +00:00
/{{< latest " telegraf " > }}/
2020-08-19 19:53:38 +00:00
```
2021-05-18 21:21:34 +00:00
### Latest patch version
2021-07-23 22:54:38 +00:00
Use the `{{< latest-patch >}}` shortcode to add the latest patch version of a product.
By default, this shortcode parses the product and minor version from the URL.
To specify a specific product and minor version, use the `product` and `version` arguments.
Easier to maintain being you update the version number in the `data/products.yml` file instead of updating individual links and code examples.
2021-05-18 21:21:34 +00:00
```md
{{< latest-patch > }}
2021-07-23 22:54:38 +00:00
{{< latest-patch product = "telegraf" > }}
{{< latest-patch product = "chronograf" version = "1.7" > }}
2021-05-18 21:21:34 +00:00
```
2021-07-30 17:35:40 +00:00
### Latest influx CLI version
Use the `{{< latest-cli >}}` shortcode to add the latest version of the `influx`
CLI supported by the minor version of InfluxDB.
By default, this shortcode parses the minor version from the URL.
To specify a specific minor version, use the `version` argument.
Maintain CLI version numbers in the `data/products.yml` file instead of updating individual links and code examples.
```md
{{< latest-cli > }}
{{< latest-cli version = "2.1" > }}
```
2021-06-28 20:57:05 +00:00
### API endpoint
Use the `{{< api-endpoint >}}` shortcode to generate a code block that contains
a colored request method and a specified API endpoint.
Provide the following arguments:
- **method**: HTTP request method (get, post, patch, put, or delete)
- **endpoint**: API endpoint
```md
{{< api-endpoint method = "get" endpoint = "/api/v2/tasks" > }}
```
2019-01-09 23:08:51 +00:00
### Tabbed Content
Shortcodes are available for creating "tabbed" content (content that is changed by a users' selection).
Ther following three must be used:
`{{< tabs-wrapper >}}`
This shortcode creates a wrapper or container for the tabbed content.
All UI interactions are limited to the scope of each container.
If you have more than one "group" of tabbed content in a page, each needs its own `tabs-wrapper` .
This shortcode must be closed with `{{< /tabs-wrapper >}}` .
**Note**: The `<` and `>` characters used in this shortcode indicate that the contents should be processed as HTML.
`{{% tabs %}}`
This shortcode creates a container for buttons that control the display of tabbed content.
It should contain simple markdown links with anonymous anchors (`#`).
The link text is used as the button text.
This shortcode must be closed with `{{% /tabs %}}` .
**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown.
`{{% tab-content %}}`
This shortcode creates a container for a content block.
Each content block in the tab group needs to be wrapped in this shortcode.
**The number of `tab-content` blocks must match the number of links provided in the `tabs` shortcode**
This shortcode must be closed with `{{% /tab-content %}}` .
**Note**: The `%` characters used in this shortcode indicate that the contents should be processed as Markdown.
#### Example tabbed content group
```md
{{< tabs-wrapper > }}
{{% tabs %}}
[Button text for tab 1 ](# )
[Button text for tab 2 ](# )
{{% /tabs %}}
{{% tab-content %}}
Markdown content for tab 1.
{{% /tab-content %}}
{{% tab-content %}}
Markdown content for tab 2.
{{% /tab-content %}}
{{< / tabs-wrapper > }}
```
#### Tabbed code blocks
Shortcodes are also available for tabbed code blocks primarily used to give users
the option to choose between different languages and syntax.
The shortcode structure is the same as above, but the shortcode names are different:
`{{< code-tabs-wrapper >}}`
`{{% code-tabs %}}`
`{{% code-tab-content %}}`
~~~md
{{< code-tabs-wrapper > }}
{{% code-tabs %}}
[Flux ](# )
[InfluxQL ](# )
{{% /code-tabs %}}
{{% code-tab-content %}}
```js
2019-05-13 22:24:09 +00:00
data = from(bucket: "example-bucket")
2019-01-09 23:08:51 +00:00
|> range(start: -15m)
|> filter(fn: (r) =>
2019-04-18 16:01:47 +00:00
r._measurement == "mem" and
2019-01-09 23:08:51 +00:00
r._field == "used_percent"
)
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```sql
SELECT "used_percent"
FROM "telegraf"."autogen"."mem"
WHERE time > now() - 15m
```
{{% /code-tab-content %}}
{{< / code-tabs-wrapper > }}
~~~
2021-07-22 14:42:16 +00:00
#### Link to tabbed content
To link to tabbed content, click on the tab and use the URL parameter shown.
It will have the form `?t=` , plus a string.
For example:
```
[Windows installation ](/influxdb/v2.0/install/?t=Windows )
```
2020-11-25 22:39:25 +00:00
### Required elements
Use the `{{< req >}}` shortcode to identify required elements in documentation with
orange text and/or asterisks. By default, the shortcode outputs the text, "Required," but
you can customize the text by passing a string argument with the shortcode.
```md
{{< req > }}
```
**Output:** Required
```md
{{< req " This is Required " > }}
```
**Output:** This is required
2021-06-28 20:57:05 +00:00
If using other named arguments like `key` or `color` , use the `text` argument to
customize the text of the required message.
```md
{{< req text = "Required if ..." color = "blue" type = "key" > }}
```
2020-11-25 22:39:25 +00:00
#### Required elements in a list
When identifying required elements in a list, use `{{< req type="key" >}}` to generate
a "* Required" key before the list. For required elements in the list, include
{{< req " \*" > }} before the text of the list item. For example:
```md
{{< req type = "key" > }}
- {{< req " \*" > }} **This element is required**
- {{< req " \*" > }} **This element is also required**
- **This element is NOT required**
```
2021-06-28 20:57:05 +00:00
#### Change color of required text
Use the `color` argument to change the color of required text.
The following colors are available:
- blue
- green
- magenta
```md
{{< req color = "magenta" text = "This is required" > }}
```
2020-11-19 20:41:21 +00:00
### Keybinds
Use the `{{< keybind >}}` shortcode to include OS-specific keybindings/hotkeys.
The following parameters are available:
- mac
- linux
- win
- all
- other
```md
<!-- Provide keybinding for one OS and another for all others -->
{{< keybind mac = "⇧⌘P" other = "Ctrl+Shift+P" > }}
<!-- Provide a keybind for all OSs -->
{{< keybind all = "Ctrl+Shift+P" > }}
<!-- Provide unique keybindings for each OS -->
{{< keybind mac = "⇧⌘P" linux = "Ctrl+Shift+P" win = "Ctrl+Shift+Alt+P" > }}
```
2020-12-22 05:49:43 +00:00
### Diagrams
Use the `{{< diagram >}}` shortcode to dynamically build diagrams.
The shortcode uses [mermaid.js ](https://github.com/mermaid-js/mermaid ) to convert
simple text into SVG diagrams.
For information about the syntax, see the [mermaid.js documentation ](https://mermaid-js.github.io/mermaid/#/ ).
```md
{{< diagram > }}
flowchart TB
This --> That
That --> There
{{< / diagram > }}
```
2021-04-29 20:04:33 +00:00
### File system diagrams
Use the `{{< filesystem-diagram >}}` shortcode to create a styled file system
diagram using a Markdown unordered list.
2021-07-07 16:53:54 +00:00
##### Example filesystem diagram shortcode
2021-04-29 20:04:33 +00:00
```md
{{< filesystem-diagram > }}
- Dir1/
- Dir2/
- ChildDir/
- Child
- Child
- Dir3/
{{< / filesystem-diagram > }}
```
2019-01-09 23:08:51 +00:00
### High-resolution images
In many cases, screenshots included in the docs are taken from high-resolution (retina) screens.
Because of this, the actual pixel dimension is 2x larger than it needs to be and is rendered 2x bigger than it should be.
The following shortcode automatically sets a fixed width on the image using half of its actual pixel dimension.
This preserves the detail of the image and renders it at a size where there should be little to no "blur"
cause by browser image resizing.
```html
{{< img-hd src = "/path/to/image" alt = "Alternate title" / > }}
```
###### Notes
- This should only be used on screenshots takes from high-resolution screens.
- The `src` should be relative to the `static` directory.
- Image widths are limited to the width of the article content container and will scale accordingly,
even with the `width` explicitly set.
### Truncated content blocks
In some cases, it may be appropriate to shorten or truncate blocks of content.
Use cases include long examples of output data or tall images.
The following shortcode truncates blocks of content and allows users to opt into
to seeing the full content block.
```md
{{% truncate %}}
Truncated markdown content here.
{{% /truncate %}}
```
2019-01-21 15:57:35 +00:00
2020-07-29 21:07:24 +00:00
### Expandable accordion content blocks
Use the `{{% expand "Item label" %}}` shortcode to create expandable, accordion-style content blocks.
Each expandable block needs a label that users can click to expand or collpase the content block.
Pass the label as a string to the shortcode.
```md
2021-02-27 01:31:19 +00:00
{{% expand "Label 1" %}}
2020-07-29 21:07:24 +00:00
Markdown content associated with label 1.
{{% /expand %}}
2021-02-27 01:31:19 +00:00
{{% expand "Label 2" %}}
2020-07-29 21:07:24 +00:00
Markdown content associated with label 2.
{{% /expand %}}
2021-02-27 01:31:19 +00:00
{{% expand "Label 3" %}}
2020-07-29 21:07:24 +00:00
Markdown content associated with label 3.
{{% /expand %}}
```
2021-02-27 01:31:19 +00:00
Use the optional `{{< expand-wrapper >}}` shortcode around a group of `{{% expand %}}`
shortcodes to ensure proper spacing around the expandable elements:
```md
{{< expand-wrapper > }}
{{% expand "Label 1" %}}
Markdown content associated with label 1.
{{% /expand %}}
{{% expand "Label 2" %}}
Markdown content associated with label 2.
{{% /expand %}}
{{< / expand-wrapper > }}
```
2021-04-29 20:04:33 +00:00
### Captions
Use the `{{% caption %}}` shortcode to add captions to images and code blocks.
Captions are styled with a smaller font size, italic text, slight transparency,
and appear directly under the previous image or code block.
```md
{{% caption %}}
Markdown content for the caption.
{{% /caption %}}
```
2019-01-22 19:04:11 +00:00
### Generate a list of children articles
Section landing pages often contain just a list of articles with links and descriptions for each.
This can be cumbersome to maintain as content is added.
To automate the listing of articles in a section, use the `{{< children >}}` shortcode.
```md
{{< children > }}
```
2019-02-06 16:09:22 +00:00
The children shortcode can also be used to list only "section" articles (those with their own children),
or only "page" articles (those with no children) using the `show` argument:
```md
{{< children show = "sections" > }}
<!-- OR -->
{{< children show = "pages" > }}
```
_By default, it displays both sections and pages._
2020-03-11 17:04:32 +00:00
Use the `type` argument to specify the format of the children list.
2019-02-06 16:09:22 +00:00
```md
{{< children type = "functions" > }}
```
2020-03-11 17:04:32 +00:00
The following list types are available:
- **articles:** lists article titles as headers with the description or summary
of the article as a paragraph. Article headers link to the articles.
- **list:** lists children article links in an unordered list.
2020-04-27 16:53:27 +00:00
- **anchored-list:** lists anchored children article links in an unordered list
meant to act as a page navigation and link to children header.
2020-03-11 17:04:32 +00:00
- **functions:** a special use-case designed for listing Flux functions.
2020-04-27 16:53:27 +00:00
#### Include a "Read more" link
To include a "Read more" link with each child summary, set `readmore=true` .
_Only the `articles` list type supports "Read more" links._
```md
{{< children readmore = true > }}
```
#### Include a horizontal rule
To include a horizontal rule after each child summary, set `hr=true` .
_Only the `articles` list type supports horizontal rules._
```md
{{< children readmore = true > }}
```
2020-03-20 17:01:37 +00:00
#### Include a code example with a child summary
Use the `list_code_example` frontmatter to provide a code example with an article
in an articles list.
~~~yaml
list_code_example: |
```sh
This is a code example
```
~~~
2021-07-07 16:53:54 +00:00
#### Organize and include native code examples
2021-07-15 22:21:52 +00:00
To include text from a file in `/shared/text/` , use the
`{{< get-shared-text >}}` shortcode and provide the relative path and filename.
2021-07-07 16:53:54 +00:00
This is useful for maintaining and referencing sample code variants in their
native file formats.
2021-07-15 22:21:52 +00:00
1. Store code examples in their native formats at `/shared/text/` .
2021-07-07 16:53:54 +00:00
```md
2021-07-15 22:21:52 +00:00
/shared/text/example1/example.js
/shared/text/example1/example.py
2021-07-07 16:53:54 +00:00
```
2. Include the files, e.g. in code tabs
````md
{{% code-tabs-wrapper %}}
{{% code-tabs %}}
[Javascript ](#js )
[Python ](#py )
{{% /code-tabs %}}
{{% code-tab-content %}}
```js
2021-07-15 22:21:52 +00:00
{{< get-shared-text " example1 / example . js " > }}
2021-07-07 16:53:54 +00:00
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```py
2021-07-15 22:21:52 +00:00
{{< get-shared-text " example1 / example . py " > }}
2021-07-07 16:53:54 +00:00
```
{{% /code-tab-content %}}
{{% /code-tabs-wrapper %}}
````
#### Include specific files from the same directory
To include the text from one file in another file in the same
directory, use the `{{< get-leaf-text >}}` shortcode.
The directory that contains both files must be a
Hugo [*Leaf Bundle* ](https://gohugo.io/content-management/page-bundles/#leaf-bundles ),
a directory that doesn't have any child directories.
In the following example, `api` is a leaf bundle. `content` isn't.
```md
content
|
|--- api
| query.pdmc
| query.sh
| _index.md
```
##### query.pdmc
```md
# Query examples
```
##### query.sh
```md
curl https://localhost:8086/query
```
To include `query.sh` and `query.pdmc` in `api/_index.md` , use the following code:
````md
{{< get-leaf-text " query . pdmc " > }}
# Curl example
```sh
{{< get-leaf-text " query . sh " > }}
```
````
Avoid using the following file extensions when naming included text files since Hugo interprets these as markup languages:
`.ad` , `.adoc` , `.asciidoc` , `.htm` , `.html` , `.markdown` , `.md` , `.mdown` , `.mmark` , `.pandoc` , `.pdc` , `.org` , or `.rst` .
2020-04-27 16:53:27 +00:00
#### Reference a query example in children
To include a query example with the children in your list, update `data/query_examples.yml`
with the example code, input, and output, and use the `list_query_example`
frontmatter to reference the corresponding example.
```yaml
list_query_example: cumulative_sum
```
2020-03-11 17:04:32 +00:00
#### Children frontmatter
Each children list `type` uses [frontmatter properties ](#page-frontmatter ) when generating the list of articles.
The following table shows which children types use which frontmatter properties:
2020-04-27 16:53:27 +00:00
| Frontmatter | articles | list | functions |
|:----------- |:--------:|:----:|:---------:|
| `list_title` | ✓ | ✓ | ✓ |
| `description` | ✓ | | |
| `external_url` | ✓ | ✓ | |
| `list_image` | ✓ | | |
| `list_note` | | ✓ | |
| `list_code_example` | ✓ | | |
| `list_query_example` | ✓ | | |
2020-03-11 17:04:32 +00:00
2019-02-28 00:15:36 +00:00
### Inline icons
The `icon` shortcode allows you to inject icons in paragraph text.
It's meant to clarify references to specific elements in the InfluxDB user interface.
```
{{< icon " icon-name " > }}
```
Below is a list of available icons (some are aliases):
2019-02-28 00:19:47 +00:00
- add-cell
- add-label
- alert
- calendar
2019-04-10 15:11:25 +00:00
- chat
2019-02-28 00:19:47 +00:00
- checkmark
- clone
2019-04-10 15:11:25 +00:00
- cloud
2019-02-28 00:19:47 +00:00
- cog
- config
- copy
- dashboard
- dashboards
- data-explorer
2019-10-07 17:22:54 +00:00
- delete
2019-02-28 00:19:47 +00:00
- download
- duplicate
- edit
- expand
- export
2019-10-07 17:22:54 +00:00
- eye
- eye-closed
- eye-open
2019-04-10 15:11:25 +00:00
- feedback
2019-02-28 00:19:47 +00:00
- fullscreen
- gear
- graph
2019-10-07 17:22:54 +00:00
- hide
2019-02-28 00:19:47 +00:00
- influx
- influx-icon
- nav-admin
- nav-config
- nav-configuration
- nav-dashboards
- nav-data-explorer
- nav-organizations
- nav-orgs
- nav-tasks
- note
2020-12-02 22:10:59 +00:00
- notebook
- notebooks
2019-02-28 00:19:47 +00:00
- org
- orgs
- pause
- pencil
- play
- plus
- refresh
- remove
- replay
- save-as
- search
- settings
- tasks
2019-10-07 17:22:54 +00:00
- toggle
- trash
- trashcan
2019-02-28 00:19:47 +00:00
- triangle
2019-10-07 17:22:54 +00:00
- view
2019-02-28 00:19:47 +00:00
- wrench
- x
2019-02-28 00:15:36 +00:00
2019-02-28 22:30:28 +00:00
### InfluxDB UI left navigation icons
In many cases, documentation references an item in the left nav of the InfluxDB UI.
2019-11-01 17:25:25 +00:00
Provide a visual example of the navigation item using the `nav-icon` shortcode.
2019-02-28 22:30:28 +00:00
```
2020-12-02 22:10:59 +00:00
{{< nav-icon " tasks " > }}
2019-02-28 22:30:28 +00:00
```
The following case insensitive values are supported:
2019-10-07 17:22:54 +00:00
- admin, influx
- data-explorer, data explorer
2020-12-02 22:10:59 +00:00
- notebooks, books
2019-02-28 22:30:28 +00:00
- dashboards
- tasks
2019-10-07 17:22:54 +00:00
- monitor, alerts, bell
- cloud, usage
- disks, load data, load-data
- settings
- feedback
2019-02-28 22:30:28 +00:00
2020-03-03 18:25:00 +00:00
### Flexbox-formatted content blocks
CSS Flexbox formatting lets you create columns in article content that adjust and
flow based on the viewable width.
In article content, this helps if you have narrow tables that could be displayed
side-by-side, rather than stacked vertically.
Use the `{{< flex >}}` shortcode to create the Flexbox wrapper.
Use the `{{% flex-content %}}` shortcode to identify each column content block.
```md
{{< flex > }}
{{% flex-content %}}
Column 1
{{% /flex-content %}}
{{% flex-content %}}
Column 2
{{% /flex-content %}}
{{< / flex > }}
```
`{{% flex-content %}}` has an optional width argument that determines the maximum
width of the column.
```md
{{% flex-content "half" %}}
```
The following options are available:
- half _(Default)_
- third
- quarter
2020-07-06 20:36:19 +00:00
### Tooltips
Use the `{{< tooltips >}}` shortcode to add tooltips to text.
The **1st** argument is the text shown in the tooltip.
The **2nd** argument is the highlighted text that triggers the tooltip.
```md
I like {{< tooltip " Butterflies are awesome ! " " butterflies " > }}.
```
The example above renders as "I like butterflies" with "butterflies" highlighted.
When you hover over "butterflies," a tooltip appears with the text: "Butterflies are awesome!"
2019-01-21 15:57:35 +00:00
### Reference content
The InfluxDB documentation is "task-based," meaning content primarily focuses on
what a user is **doing** , not what they are **using** .
However, there is a need to document tools and other things that don't necessarily
fit in the task-based style.
This is referred to as "reference content."
Reference content is styled just as the rest of the InfluxDB documentation.
The only difference is the `menu` reference in the page's frontmatter.
When defining the menu for reference content, use the following pattern:
```yaml
# Pattern
menu:
2020-08-06 17:48:47 +00:00
< project > _< major-version-number > _< minor-version-number > _ref:
2019-01-21 15:57:35 +00:00
# ...
# Example
menu:
2020-07-28 22:34:16 +00:00
influxdb_2_0_ref:
2019-01-21 15:57:35 +00:00
# ...
```
2020-09-11 21:18:18 +00:00
2020-04-20 20:47:04 +00:00
## InfluxDB URLs
2020-04-22 17:23:49 +00:00
When a user selects an InfluxDB product and region, example URLs in code blocks
throughout the documentation are updated to match their product and region.
2020-04-20 20:47:04 +00:00
InfluxDB URLs are configured in `/data/influxdb_urls.yml` .
2020-09-04 18:26:51 +00:00
By default, the InfluxDB URL replaced inside of code blocks is `http://localhost:8086` .
2020-04-22 17:23:49 +00:00
Use this URL in all code examples that should be updated with a selected provider and region.
For example:
~~~
```sh
# This URL will get updated
2020-09-04 18:26:51 +00:00
http://localhost:8086
2020-04-22 17:23:49 +00:00
# This URL will NOT get updated
http://example.com
```
~~~
2020-09-04 18:26:51 +00:00
If the user selects the **US West (Oregon)** region, all occurrences of `http://localhost:8086`
2020-04-22 17:23:49 +00:00
in code blocks will get updated to `https://us-west-2-1.aws.cloud2.influxdata.com` .
### Exempt URLs from getting updated
2020-04-20 20:47:04 +00:00
To exempt a code block from being updated, include the `{{< keep-url >}}` shortcode
just before the code block.
~~~
{{< keep-url > }}
```
// This URL won't get updated
2020-09-04 18:26:51 +00:00
http://localhost:8086
2020-04-20 20:47:04 +00:00
```
~~~
2020-07-12 04:25:25 +00:00
### Code examples only supported in InfluxDB Cloud
Some functionality is only supported in InfluxDB Cloud and code examples should
only use InfluxDB Cloud URLs. In these cases, use `https://cloud2.influxdata.com`
as the placeholder in the code block. It will get updated on page load and when
users select a Cloud region in the URL select modal.
~~~
```sh
# This URL will get updated
https://cloud2.influxdata.com
```
~~~
2019-02-05 19:05:40 +00:00
## New Versions of InfluxDB
Version bumps occur regularly in the documentation.
Each minor version has its own directory with unique content.
Patch versions within a minor version are updated in place.
To add a new minor version, go through the steps below.
_This example assumes v2.0 is the most recent version and v2.1 is the new version._
1. Ensure your `master` branch is up to date:
```sh
git checkout master
git pull
```
2. Create a new branch for the new minor version:
```sh
git checkout -b influxdb-2.1
```
3. Duplicate the most recent version's content directory:
```sh
# From the root of the project
2020-07-29 16:02:10 +00:00
cp content/influxdb/v2.0 content/influxdb/v2.1
2019-02-05 19:05:40 +00:00
```
4. Find and replace all instances of the old version number with the new version
** (only within the new version directory)**.
Be sure to find and replace both the following forms of the version number:
2020-07-29 16:02:10 +00:00
2019-02-05 19:05:40 +00:00
```
v2.0 -> v2.1
v2_0 -> v2_1
```
2020-07-29 16:02:10 +00:00
5. Add the new product and version tag taxonomy to the `config.toml` in the root of the project.
2019-02-05 19:05:40 +00:00
```toml
[taxonomies]
2020-07-29 16:02:10 +00:00
"influxdb/v2.0/tag" = "influxdb/v2.0/tags"
"influxdb/v2.1/tag" = "influxdb/v2.1/tags"
2019-02-05 19:05:40 +00:00
```
2021-07-29 02:04:23 +00:00
6. Update the `latest_version` in `data/products.yml` :
2019-02-05 19:05:40 +00:00
```yaml
latest_version: v2.1
```
2019-10-07 17:22:54 +00:00
7. Copy the InfluxDB `swagger.yml` specific to the new version into the
`/api-docs/v<version-number>/` directory.
8. Commit the changes and push the new branch to Github.
2019-02-05 19:05:40 +00:00
These changes lay the foundation for the new version.
All other changes specific to the new version should be merged into this branch.
Once the necessary changes are in place and the new version is released,
merge the new branch into `master` .
2020-12-23 20:54:08 +00:00
## InfluxDB API documentation
InfluxData uses [Redoc ](https://github.com/Redocly/redoc ) to generate the full
InfluxDB API documentation when documentation is deployed.
Redoc generates HTML documentation using the InfluxDB `swagger.yml` .
For more information about generating InfluxDB API documentation, see the
[API Documentation README ](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme ).
