influxdata
diff --git a/‎DOCS-SHORTCODES.md‎
Lines changed: 90 additions & 28 deletions b/‎DOCS-SHORTCODES.md‎
Lines changed: 90 additions & 28 deletions
diff --git a/‎README.md‎
Lines changed: 53 additions & 24 deletions b/‎README.md‎
Lines changed: 53 additions & 24 deletions
@@ -19,7 +19,7 @@ Complete reference for custom Hugo shortcodes used in InfluxData documentation.
 - [Content Management](#content-management)
 - [Special Purpose](#special-purpose)
 
----
+***
 
 ## Notes and Warnings
 
@@ -146,7 +146,7 @@ Use the `{{< api-endpoint >}}` shortcode to generate a code block that contains
 - **method**: HTTP request method (get, post, patch, put, or delete)
 - **endpoint**: API endpoint
 - **api-ref**: Link the endpoint to a specific place in the API documentation
-- **influxdb_host**: Specify which InfluxDB product host to use _if the `endpoint` contains the `influxdb/host` shortcode_. Uses the current InfluxDB product as default. Supports the following product values:
+- **influxdb_host**: Specify which InfluxDB product host to use *if the `endpoint` contains the `influxdb/host` shortcode*. Uses the current InfluxDB product as default. Supports the following product values:
   - oss
   - cloud
   - serverless
@@ -268,11 +268,11 @@ To link to tabbed content, click on the tab and use the URL parameter shown. It
 
 Use the `{{< page-nav >}}` shortcode to add page navigation buttons to a page. These are useful for guiding users through a set of docs that should be read in sequential order. The shortcode has the following parameters:
 
-- **prev:** path of the previous document _(optional)_
-- **next:** path of the next document _(optional)_
-- **prevText:** override the button text linking to the previous document _(optional)_
-- **nextText:** override the button text linking to the next document _(optional)_
-- **keepTab:** include the currently selected tab in the button link _(optional)_
+- **prev:** path of the previous document *(optional)*
+- **next:** path of the next document *(optional)*
+- **prevText:** override the button text linking to the previous document *(optional)*
+- **nextText:** override the button text linking to the next document *(optional)*
+- **keepTab:** include the currently selected tab in the button link *(optional)*
 
 The shortcode generates buttons that link to both the previous and next documents. By default, the shortcode uses either the `list_title` or the `title` of the linked document, but you can use `prevText` and `nextText` to override button text.
 
@@ -308,7 +308,7 @@ The children shortcode can also be used to list only "section" articles (those w
 {{< children show="pages" >}}
 ```
 
-_By default, it displays both sections and pages._
+*By default, it displays both sections and pages.*
 
 Use the `type` argument to specify the format of the children list.
 
@@ -325,15 +325,15 @@ The following list types are available:
 
 #### 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._
+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._
+To include a horizontal rule after each child summary, set `hr=true`. *Only the `articles` list type supports horizontal rules.*
 
 ```md
 {{< children hr=true >}}
@@ -390,11 +390,11 @@ This is useful for maintaining and referencing sample code variants in their nat
 
 #### Include specific files from the same directory
 
-> [!Caution]
+> \[!Caution]
 > **Don't use for code examples**
 > Using this and `get-shared-text` shortcodes to include code examples prevents the code from being tested.
 
-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.
+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.
 
@@ -447,13 +447,13 @@ Each children list `type` uses frontmatter properties when generating the list o
 
 | Frontmatter          | articles | list | functions |
 | :------------------- | :------: | :--: | :-------: |
-| `list_title`         |    ✓     |  ✓   |     ✓     |
-| `description`        |    ✓     |      |           |
-| `external_url`       |    ✓     |  ✓   |           |
-| `list_image`         |    ✓     |      |           |
-| `list_note`          |          |  ✓   |           |
-| `list_code_example`  |    ✓     |      |           |
-| `list_query_example` |    ✓     |      |           |
+| `list_title`         |     ✓    |   ✓  |     ✓     |
+| `description`        |     ✓    |      |           |
+| `external_url`       |     ✓    |   ✓  |           |
+| `list_image`         |     ✓    |      |           |
+| `list_note`          |          |   ✓  |           |
+| `list_code_example`  |     ✓    |      |           |
+| `list_query_example` |     ✓    |      |           |
 
 ## Visual Elements
 
@@ -695,7 +695,7 @@ Column 2
 
 The following options are available:
 
-- half _(Default)_
+- half *(Default)*
 - third
 - quarter
 
@@ -721,10 +721,10 @@ Click {{< caps >}}Add Data{{< /caps >}}
 
 ### Authentication token link
 
-Use the `{{% token-link "<descriptor>" "<link_append>%}}` shortcode to automatically generate links to token management documentation. The shortcode accepts two _optional_ arguments:
+Use the `{{% token-link "<descriptor>" "<link_append>%}}` shortcode to automatically generate links to token management documentation. The shortcode accepts two *optional* arguments:
 
 - **descriptor**: An optional token descriptor
-- **link_append**: An optional path to append to the token management link path, `/<product>/<version>/admin/tokens/`.
+- **link\_append**: An optional path to append to the token management link path, `/<product>/<version>/admin/tokens/`.
 
 ```md
 {{% token-link "database" "resource/" %}}
@@ -775,7 +775,7 @@ Descriptions should follow consistent patterns:
    - Recommended: "your {{% token-link "database" %}}"{{% show-in "enterprise" %}} with permissions on the specified database{{% /show-in %}}
    - Avoid: "your token", "the token", "an authorization token"
 3. **Database names**:
-   - Recommended: "the name of the database to [action]"
+   - Recommended: "the name of the database to \[action]"
    - Avoid: "your database", "the database name"
 4. **Conditional content**:
    - Use `{{% show-in "enterprise" %}}` for content specific to enterprise versions
@@ -797,13 +797,75 @@ Descriptions should follow consistent patterns:
 
 #### Syntax
 
--  `{ placeholders="PATTERN1|PATTERN2" }`: Use this code block attribute to define placeholder patterns
+- `{ placeholders="PATTERN1|PATTERN2" }`: Use this code block attribute to define placeholder patterns
 - `{{% code-placeholder-key %}}`: Use this shortcode to define a placeholder key
 - `{{% /code-placeholder-key %}}`: Use this shortcode to close the key name
 
-_The `placeholders` attribute supercedes the deprecated `code-placeholders` shortcode._
+*The `placeholders` attribute supercedes the deprecated `code-placeholders` shortcode.*
+
+#### Automated placeholder syntax
+
+Use the `docs placeholders` command to automatically add placeholder syntax to code blocks and descriptions:
+
+```bash
+# Process a file
+npx docs placeholders content/influxdb3/core/admin/upgrade.md
+
+# Preview changes without modifying the file
+npx docs placeholders content/influxdb3/core/admin/upgrade.md --dry
+
+# Get help
+npx docs placeholders --help
+```
+
+**What it does:**
+
+1. Detects UPPERCASE placeholders in code blocks
+2. Adds `{ placeholders="..." }` attribute to code fences
+3. Wraps placeholder descriptions with `{{% code-placeholder-key %}}` shortcodes
+
+**Example transformation:**
+
+Before:
+
+````markdown
+```bash
+influxdb3 query \
+  --database SYSTEM_DATABASE \
+  --token ADMIN_TOKEN \
+  "SELECT * FROM system.version"
+```
+
+Replace the following:
+
+- **`SYSTEM_DATABASE`**: The name of your system database
+- **`ADMIN_TOKEN`**: An admin token with read permissions
+````
+
+After:
+
+````markdown
+```bash { placeholders="ADMIN_TOKEN|SYSTEM_DATABASE" }
+influxdb3 query \
+  --database SYSTEM_DATABASE \
+  --token ADMIN_TOKEN \
+  "SELECT * FROM system.version"
+```
+
+Replace the following:
+
+- {{% code-placeholder-key %}}`SYSTEM_DATABASE`{{% /code-placeholder-key %}}: The name of your system database
+- {{% code-placeholder-key %}}`ADMIN_TOKEN`{{% /code-placeholder-key %}}: An admin token with read permissions
+````
+
+**How it works:**
+
+- Pattern: Matches words with 2+ characters, all uppercase, can include underscores
+- Excludes common words: HTTP verbs (GET, POST), protocols (HTTP, HTTPS), SQL keywords (SELECT, FROM), etc.
+- Idempotent: Running multiple times won't duplicate syntax
+- Preserves existing `placeholders` attributes and already-wrapped descriptions
 
-#### Example usage
+#### Manual placeholder usage
 
 ```sh { placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|[email protected]" }
 curl --request POST http://localhost:8086/write?db=DATABASE_NAME \
@@ -839,7 +901,7 @@ Sample dataset to output. Use either `set` argument name or provide the set as t
 
 #### includeNull
 
-Specify whether or not to include _null_ values in the dataset. Use either `includeNull` argument name or provide the boolean value as the second argument.
+Specify whether or not to include *null* values in the dataset. Use either `includeNull` argument name or provide the boolean value as the second argument.
 
 #### includeRange
 
@@ -1115,6 +1177,6 @@ The InfluxDB host placeholder that gets replaced by custom domains differs betwe
 {{< influxdb/host "serverless" >}}
 ```
 
----
+***
 
 **For working examples**: Test all shortcodes in [content/example.md](content/example.md)
@@ -2,9 +2,9 @@
   <img src="/static/img/influx-logo-cubo-dark.png" width="200">
 </p>
 
-# InfluxDB 2.0 Documentation
+# InfluxData Product Documentation
 
-This repository contains the InfluxDB 2.x documentation published at [docs.influxdata.com](https://docs.influxdata.com).
+This repository contains the InfluxData product documentation for InfluxDB and related tooling published at [docs.influxdata.com](https://docs.influxdata.com).
 
 ## Contributing
 
@@ -15,6 +15,26 @@ For information about contributing to the InfluxData documentation, see [Contrib
 
 For information about testing the documentation, including code block testing, link validation, and style linting, see [Testing guide](DOCS-TESTING.md).
 
+## Documentation Tools
+
+This repository includes a `docs` CLI tool for common documentation workflows:
+
+```sh
+# Create new documentation from a draft
+npx docs create drafts/new-feature.md --products influxdb3_core
+
+# Edit existing documentation from a URL
+npx docs edit https://docs.influxdata.com/influxdb3/core/admin/
+
+# Add placeholder syntax to code blocks
+npx docs placeholders content/influxdb3/core/admin/upgrade.md
+
+# Get help
+npx docs --help
+```
+
+The `docs` command is automatically configured when you run `yarn install`.
+
 ## Documentation
 
 Comprehensive reference documentation for contributors:
@@ -27,6 +47,7 @@ Comprehensive reference documentation for contributors:
 - **[API Documentation](api-docs/README.md)** - API reference generation
 
 ### Quick Links
+
 - [Style guidelines](DOCS-CONTRIBUTING.md#style-guidelines)
 - [Commit guidelines](DOCS-CONTRIBUTING.md#commit-guidelines)
 - [Code block testing](DOCS-TESTING.md#code-block-testing)
@@ -35,42 +56,49 @@ Comprehensive reference documentation for contributors:
 
 InfluxData takes security and our users' trust very seriously.
 If you believe you have found a security issue in any of our open source projects,
-please responsibly disclose it by contacting [email protected].
+please responsibly disclose it by contacting <[email protected]>.
 More details about security vulnerability reporting,
-including our GPG key, can be found at https://www.influxdata.com/how-to-report-security-vulnerabilities/.
+including our GPG key, can be found at <https://www.influxdata.com/how-to-report-security-vulnerabilities/>.
 
 ## Running the docs locally
 
 1. [**Clone this repository**](https://help.github.com/articles/cloning-a-repository/) to your local machine.
 
-2.  **Install NodeJS, Yarn, Hugo, & Asset Pipeline Tools**
+2. **Install NodeJS, Yarn, Hugo, & Asset Pipeline Tools**
+
+   The InfluxData documentation uses [Hugo](https://gohugo.io/), a static site generator built in Go. The site uses Hugo's asset pipeline, which requires the extended version of Hugo along with NodeJS tools like PostCSS, to build and process stylesheets and JavaScript.
 
-    The InfluxData documentation uses [Hugo](https://gohugo.io/), a static site generator built in Go. The site uses Hugo's asset pipeline, which requires the extended version of Hugo along with NodeJS tools like PostCSS, to build and process stylesheets and JavaScript.
+   To install the required dependencies and build the assets, do the following:
 
-    To install the required dependencies and build the assets, do the following:
+   1. [Install NodeJS](https://nodejs.org/en/download/)
+   2. [Install Yarn](https://classic.yarnpkg.com/en/docs/install/)
+   3. In your terminal, from the `docs-v2` directory, install the dependencies:
 
-    1. [Install NodeJS](https://nodejs.org/en/download/)
-    2. [Install Yarn](https://classic.yarnpkg.com/en/docs/install/)
-    3. In your terminal, from the `docs-v2` directory, install the dependencies:
+      ```sh
+      cd docs-v2
+      yarn install
+      ```
+
+      ***Note:** The most recent version of Hugo tested with this documentation is **0.149.0**.*
 
-          ```sh
-          cd docs-v2
-          yarn install
-          ```
+      After installation, the `docs` command will be available via `npx`:
 
-       _**Note:** The most recent version of Hugo tested with this documentation is **0.149.0**._
+      ```sh
+      npx docs --help
+      ```
 
 3. To generate the API docs, see [api-docs/README.md](api-docs/README.md).
 
-4.  **Start the Hugo server**
+4. **Start the Hugo server**
 
-    Hugo provides a local development server that generates the HTML pages, builds the static assets, 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`.
 
-    In your terminal, start the Hugo server:
+   In your terminal, start the Hugo server:
+
+   ```sh
+   npx hugo server
+   ```
 
-      ```sh
-      npx hugo server
-      ```
 5. View the docs at [localhost:1313](http://localhost:1313).
 
 ### Alternative: Use docker compose
@@ -81,7 +109,8 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report-
 
 3. Use Docker Compose to start the Hugo server in development mode--for example, enter the following command in your terminal:
 
-    ```sh
-    docker compose up local-dev
-    ```
+   ```sh
+   docker compose up local-dev
+   ```
+
 4. View the docs at [localhost:1313](http://localhost:1313).