influxdata · sanderson · Jan 9, 2019 · Dec 19, 2018 · Dec 19, 2018 · Dec 20, 2018
@@ -5,3 +5,4 @@ deploy
 .*.swp
 node_modules
 *.log
+/resources
@@ -1,19 +1,242 @@
 # Contributing to InfluxData Documentation
 
-We welcome (and encourage!) contributions from the community.
-
-- Sign the [InfluxData Contributor License Agreement (CLA)](https://www.influxdata.com/legal/cla/).
-
-- [Downlaod and install Hugo](http://gohugo.io/overview/installing/).
-- Fork this repository on GitHub.
-- Clone the repo to your local computer.
-
-    ```bash
-    git clone https://github.com/your_username/docs.influxdata.com.git
-    cd docs.influxdata.com/
-    ```
-- Make your changes.
-- Make sure the site compiles locally with `hugo server --watch`.
-- Check it out at [localhost:1313](http://localhost:1313/).
-- Submit a pull request.
-- Earn the respect, admiration, and eternal love of the entire InfluxData community.
+## 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.
+In order to contribute to any InfluxData project, you must first sign the CLA.
+
+[Sign the InfluxData (CLA)](https://www.influxdata.com/legal/cla/)
+
+## 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
+-Data are taking off. Those data are time series. You need a database that specializes in time series. You should check out InfluxDB.
++Data are taking off. Those data are time series. You need a database that specializes in time series. You need InfluxDB.
+```
+
+**Diff with semantic linefeeds:**
+``` diff
+Data are taking off.
+Those data are time series.
+You need a database that specializes in time series.
+-You should check out InfluxDB.
++You need InfluxDB.
+```
+
+### Page frontmatter
+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 the page's h1
+seotitle: # Page title used in the html <head> title and used in search engine results
+description: # Page description displayed in search engine results
+menu:
+  v2_0:
+    name: # Article name that only appears in the left nav
+    parent: # Specifies a parent group and nests navigation items
+    weight: # Determines sort order.
+draft: # If true, will not render page on build
+enterprise_all: # If true, specifies the doc as a whole is specific to InfluxDB Enterprise
+enterprise_some: # If true, specifies the doc includes some content specific to InfluxDB Enterprise
+```
+
+#### Title usage
+
+##### `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.
+
+##### `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.
+
+### 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.
+
+### 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
+Many articles are unique to InfluxDB enterprise or at least contain some information specific to InfluxDB Enterprise.
+There are frontmatter options and an enterprise shortcode that help to properly identify this content.
+
+#### All content is Enterprise-specific
+If all content in an article is Enterprise-specific, set the `enterprise_all` frontmatter to `true`.
+
+```yaml
+enterprise_all: true
+```
+
+This will display a message at the top of page indicating that the things discussed are unique to InfluxDB Enterprise.
+
+#### Only some content is Enterprise-specific
+If only some content in the article is enterprise specific, set the `enterprise_some` frontmatter to `true`.
+
+```yaml
+enterprise_some: true
+```
+
+This will display a message at the top of page indicating some things are unique to InfluxDB Enterprise.
+To format Enterprise-specific content, wrap it in the `{{% enterprise %}}` shortcode:
+
+```md
+{{% enterprise %}}
+Insert enterprise-specific markdown content here.
+{{% /enterprise %}}
+```
+
+### 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
+data = from(bucket: "telegraf/autogen")
+  |> range(start: -15m)
+  |> filter(fn: (r) =>
+    r._measurement == "mem" AND
+    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 >}}
+~~~
+
+### 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 %}}
+```
@@ -1,19 +1,35 @@
 # InfluxDB v2.0 Documentation
-This is the repository represents the InfluxDB v2.x documentation that will be
+This is the repository contains the InfluxDB v2.x documentation that will be
 accessible at [docs.influxdata.com](https://docs.influxdata.com).
 
+## Contributing
+We welcome and encourage community contributions to the InfluxData See our [Contribution guidelines](blob/master/CONTRIBUTING.md) for information
+about contributing to the InfluxData documentation.
+
 ## Run the docs locally
+The InfluxData documentation uses [Hugo](https://gohugo.io/), a static site
+generator built in Go.
+
+### Clone this repository
+[Clone this repository](https://help.github.com/articles/cloning-a-repository/)
+to your local machine.
 
 ### Install Hugo
-Hugo is the static site generator used to build the InfluxData documentation.
-[Download and install Hugo](https://gohugo.io/getting-started/installing/) to run the docs locally.
+See the Hugo documentation for information about how to
+[download and install Hugo](https://gohugo.io/getting-started/installing/).
+
+### Install NodeJS & Asset Pipeline Tools
+This project uses tools written in NodeJS to build and process stylesheets and javascript.
+In order for assets to build correctly, [install NodeJS](https://nodejs.org/en/download/)
+and run the following command to install the necessary tools:
 
-### Fork and clone the docs 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.
+```sh
+npm i -g postcss-cli autoprefixer
+```
 
 ### Start the hugo server
-Hugo provides a local development server that generates the HTML pages and serves them
-at `localhost:1313`.
+Hugo provides a local development server that generates the HTML pages, builds
+the static assets, and serves them at `localhost:1313`.
 
 Start the hugo server with:
 
@@ -22,66 +38,3 @@ hugo server
 ```
 
 View the docs at [localhost:1313](http://localhost:1313).
-
-## Contributing
-See our [Contribution guidelines](blob/master/CONTRIBUTING.md) for information
-about contributing to the InfluxData documentation.
-
-## 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
--Data are taking off. Those data are time series. You need a database that specializes in time series. You should check out InfluxDB.
-+Data are taking off. Those data are time series. You need a database that specializes in time series. You need InfluxDB.
-```
-
-**Diff with semantic linefeeds:**
-``` diff
-Data are taking off.
-Those data are time series.
-You need a database that specializes in time series.
--You should check out InfluxDB.
-+You need InfluxDB.
-```
-
-### Page frontmatter
-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 the page's h1
-seotitle: # Page title used in the html <head> title and used in search engine results
-description: # Page description displayed in search engine results
-menu:
-  v2_0:
-    name: # Article name that only appears in the left nav
-    parent: # Specifies a parent group and nests navigation items
-    weight: # Determines sort order.
-draft: # If true, will not render page on build
-```
-
-#### Title usage
-
-##### `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.
-
-##### `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.
-
-### 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.
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,4 @@ deploy @@
     .*.swp
     node_modules
     *.log
+    /resources