- Redesign of the docs CLI tools for creating and editing content
- Cleaner interface works better for piping output to agents and downstream utilities - Updates README.md and other authoring docs This repository includes a `docs` CLI tool for common documentation workflows: ```sh npx docs create drafts/new-feature.md --products influxdb3_core npx docs edit https://docs.influxdata.com/influxdb3/core/admin/ npx docs placeholders content/influxdb3/core/admin/upgrade.md npx docs --help ```jts-multifile-plugins-guide
Jason Stirnaman
parent
86ed2e3f9e
commit
be87ffc5b7
|
|
@ -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,7 +325,7 @@ 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 >}}
|
||||
|
|
@ -333,7 +333,7 @@ To include a "Read more" link with each child summary, set `readmore=true`. _Onl
|
|||
|
||||
#### 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.*
|
||||
|
||||
#### Example usage
|
||||
#### 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
|
||||
|
||||
#### Manual placeholder usage
|
||||
|
||||
```sh { placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" }
|
||||
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)
|
||||
|
|
|
|||
77
README.md
77
README.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 security@influxdata.com.
|
||||
please responsibly disclose it by contacting <security@influxdata.com>.
|
||||
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
|
||||
```
|
||||
```sh
|
||||
cd docs-v2
|
||||
yarn install
|
||||
```
|
||||
|
||||
_**Note:** The most recent version of Hugo tested with this documentation is **0.149.0**._
|
||||
***Note:** The most recent version of Hugo tested with this documentation is **0.149.0**.*
|
||||
|
||||
After installation, the `docs` command will be available via `npx`:
|
||||
|
||||
```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).
|
||||
|
|
|
|||
|
|
@ -61,19 +61,19 @@ Use `docs` scripts with AI agents to help you create and edit documentation loca
|
|||
|
||||
### Edit an existing page locally
|
||||
|
||||
Use the `yarn docs:edit` command to open an existing page in your editor.
|
||||
Use the `npx docs edit` command to open an existing page in your editor.
|
||||
|
||||
```bash
|
||||
yarn docs:edit https://docs.influxdata.com/influxdb3/enterprise/get-started/
|
||||
npx docs edit https://docs.influxdata.com/influxdb3/enterprise/get-started/
|
||||
```
|
||||
|
||||
### Create content locally
|
||||
|
||||
Use the `yarn docs:create` command with your AI agent tool to scaffold frontmatter and generate new content.
|
||||
Use the `npx docs create` command with your AI agent tool to scaffold frontmatter and generate new content.
|
||||
|
||||
- The `yarn docs:create` command accepts draft input from stdin or from a file path and generates a prompt file from the draft and your product selections
|
||||
- The `npx docs create` command accepts draft input from stdin or from a file path and generates a prompt file from the draft and your product selections
|
||||
- The prompt file makes AI agents aware of InfluxData docs guidelines, shared content, and product-specific requirements
|
||||
- `yarn docs:create` is designed to work automatically with `claude`, but you can
|
||||
- `npx docs create` is designed to work automatically with `claude`, but you can
|
||||
use the generated prompt file with any AI agent (for example, `copilot` or `codex`)
|
||||
|
||||
> \[!Tip]
|
||||
|
|
@ -100,11 +100,11 @@ Use the `yarn docs:create` command with your AI agent tool to scaffold frontmatt
|
|||
claude code
|
||||
```
|
||||
|
||||
2. In the prompt, run the `docs:create` command with the path to your draft file.
|
||||
2. In the prompt, run the `docs create` command with the path to your draft file.
|
||||
Optionally, include the `--products` flag and product namespaces to preselect products--for example:
|
||||
|
||||
```bash
|
||||
yarn docs:create .context/drafts/"Upgrading Enterprise 3 (draft).md" \
|
||||
npx docs create .context/drafts/"Upgrading Enterprise 3 (draft).md" \
|
||||
--products influxdb3_enterprise,influxdb3_core
|
||||
```
|
||||
|
||||
|
|
@ -115,14 +115,13 @@ The script first generates a prompt file, then the agent automatically uses it t
|
|||
{{% /tab-content %}}
|
||||
{{% tab-content %}}
|
||||
|
||||
Use `docs:create` to generate a prompt file and then pipe it to your preferred AI agent.
|
||||
Use `npx docs create` to generate a prompt file and then pipe it to your preferred AI agent.
|
||||
Include the `--products` flag and product namespaces to preselect products
|
||||
|
||||
The following example uses Copilot to process a draft file:
|
||||
|
||||
```bash
|
||||
yarn --silent \
|
||||
docs:create .context/drafts/"Upgrading Enterprise 3 (draft).md" \
|
||||
npx docs create .context/drafts/"Upgrading Enterprise 3 (draft).md" \
|
||||
--products "influxdb3_enterprise,influxdb3_core" | \
|
||||
copilot --prompt --allow-all-tools
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
# Test URL Handling
|
||||
|
||||
This is a test draft to see how the script handles URLs in content.
|
||||
|
||||
Here's a link to the InfluxDB documentation: <https://docs.influxdata.com/influxdb3/core/>
|
||||
|
||||
And here's a link to GitHub: <https://github.com/influxdata/docs-v2>
|
||||
|
||||
The script should analyze this content and determine where to place it in the documentation structure.
|
||||
|
|
@ -43,6 +43,7 @@
|
|||
"vanillajs-datepicker": "^1.3.4"
|
||||
},
|
||||
"scripts": {
|
||||
"postinstall": "node scripts/setup-local-bin.js",
|
||||
"docs:create": "node scripts/docs-create.js",
|
||||
"docs:edit": "node scripts/docs-edit.js",
|
||||
"docs:add-placeholders": "node scripts/add-placeholders.js",
|
||||
|
|
|
|||
|
|
@ -1,108 +0,0 @@
|
|||
# Add Placeholders Script
|
||||
|
||||
Automatically adds placeholder syntax to code blocks and placeholder descriptions in markdown files.
|
||||
|
||||
## What it does
|
||||
|
||||
This script finds UPPERCASE placeholders in code blocks and:
|
||||
|
||||
1. **Adds `{ placeholders="PATTERN1|PATTERN2" }` attribute** to code block fences
|
||||
2. **Wraps placeholder descriptions** with `{{% code-placeholder-key %}}` shortcodes
|
||||
|
||||
## Usage
|
||||
|
||||
### Direct usage
|
||||
|
||||
```bash
|
||||
# Process a single file
|
||||
node scripts/add-placeholders.js <file.md>
|
||||
|
||||
# Dry run to preview changes
|
||||
node scripts/add-placeholders.js <file.md> --dry
|
||||
|
||||
# Example
|
||||
node scripts/add-placeholders.js content/influxdb3/enterprise/admin/upgrade.md
|
||||
```
|
||||
|
||||
### Using npm script
|
||||
|
||||
```bash
|
||||
# Process a file
|
||||
yarn docs:add-placeholders <file.md>
|
||||
|
||||
# Dry run
|
||||
yarn docs:add-placeholders <file.md> --dry
|
||||
```
|
||||
|
||||
## Example transformations
|
||||
|
||||
### 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
|
||||
|
||||
### Placeholder detection
|
||||
|
||||
The script automatically detects UPPERCASE placeholders in code blocks using these rules:
|
||||
|
||||
- **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.
|
||||
|
||||
### Code block processing
|
||||
|
||||
1. Finds all code blocks (including indented ones)
|
||||
2. Extracts UPPERCASE placeholders
|
||||
3. Adds `{ placeholders="..." }` attribute to the fence line
|
||||
4. Preserves indentation and language identifiers
|
||||
|
||||
### Description wrapping
|
||||
|
||||
1. Detects "Replace the following:" sections
|
||||
2. Wraps placeholder descriptions matching `- **`PLACEHOLDER`**: description`
|
||||
3. Preserves indentation and formatting
|
||||
4. Skips already-wrapped descriptions
|
||||
|
||||
## Options
|
||||
|
||||
- `--dry` or `-d`: Preview changes without modifying files
|
||||
|
||||
## Notes
|
||||
|
||||
- The script is idempotent - running it multiple times on the same file won't duplicate syntax
|
||||
- Preserves existing `placeholders` attributes in code blocks
|
||||
- Works with both indented and non-indented code blocks
|
||||
- Handles multiple "Replace the following:" sections in a single file
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [DOCS-SHORTCODES.md](../DOCS-SHORTCODES.md) - Complete shortcode reference
|
||||
- [DOCS-CONTRIBUTING.md](../DOCS-CONTRIBUTING.md) - Placeholder conventions and style guidelines
|
||||
|
|
@ -16,7 +16,7 @@ import { readFileSync, writeFileSync } from 'fs';
|
|||
import { parseArgs } from 'node:util';
|
||||
|
||||
// Parse command-line arguments
|
||||
const { positionals } = parseArgs({
|
||||
const { positionals, values } = parseArgs({
|
||||
allowPositionals: true,
|
||||
options: {
|
||||
dry: {
|
||||
|
|
@ -24,19 +24,47 @@ const { positionals } = parseArgs({
|
|||
short: 'd',
|
||||
default: false,
|
||||
},
|
||||
help: {
|
||||
type: 'boolean',
|
||||
short: 'h',
|
||||
default: false,
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Show help if requested
|
||||
if (values.help) {
|
||||
console.log(`
|
||||
Add placeholder syntax to code blocks
|
||||
|
||||
Usage:
|
||||
docs placeholders <file.md> [options]
|
||||
|
||||
Options:
|
||||
--dry, -d Preview changes without modifying files
|
||||
--help, -h Show this help message
|
||||
|
||||
Examples:
|
||||
docs placeholders content/influxdb3/enterprise/admin/upgrade.md
|
||||
docs placeholders content/influxdb3/core/admin/databases/create.md --dry
|
||||
|
||||
What it does:
|
||||
1. Finds UPPERCASE placeholders in code blocks
|
||||
2. Adds { placeholders="PATTERN1|PATTERN2" } attribute to code fences
|
||||
3. Wraps placeholder descriptions with {{% code-placeholder-key %}} shortcodes
|
||||
`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
if (positionals.length === 0) {
|
||||
console.error('Usage: node scripts/add-placeholders.js <file.md> [--dry]');
|
||||
console.error(
|
||||
'Example: node scripts/add-placeholders.js content/influxdb3/enterprise/admin/upgrade.md'
|
||||
);
|
||||
console.error('Error: Missing file path argument');
|
||||
console.error('Usage: docs placeholders <file.md> [--dry]');
|
||||
console.error('Run "docs placeholders --help" for more information');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const filePath = positionals[0];
|
||||
const isDryRun = process.argv.includes('--dry') || process.argv.includes('-d');
|
||||
const isDryRun = values.dry;
|
||||
|
||||
/**
|
||||
* Extract UPPERCASE placeholders from a code block
|
||||
|
|
|
|||
|
|
@ -2,11 +2,12 @@
|
|||
|
||||
/**
|
||||
* Main CLI entry point for docs tools
|
||||
* Supports subcommands: create, edit, etc.
|
||||
* Supports subcommands: create, edit, placeholders
|
||||
*
|
||||
* Usage:
|
||||
* docs create <draft-path> [options]
|
||||
* docs edit <url> [options]
|
||||
* docs placeholders <file.md> [options]
|
||||
*/
|
||||
|
||||
import { fileURLToPath } from 'url';
|
||||
|
|
@ -24,6 +25,7 @@ const args = process.argv.slice(3);
|
|||
const subcommands = {
|
||||
create: 'docs-create.js',
|
||||
edit: 'docs-edit.js',
|
||||
placeholders: 'add-placeholders.js',
|
||||
};
|
||||
|
||||
/**
|
||||
|
|
@ -36,14 +38,17 @@ Usage: docs <command> [options]
|
|||
Commands:
|
||||
create <draft-path> Create new documentation from draft
|
||||
edit <url> Edit existing documentation
|
||||
placeholders <file.md> Add placeholder syntax to code blocks
|
||||
|
||||
Examples:
|
||||
docs create drafts/new-feature.md --products influxdb3_core
|
||||
docs edit https://docs.influxdata.com/influxdb3/core/admin/
|
||||
docs placeholders content/influxdb3/core/admin/upgrade.md
|
||||
|
||||
For command-specific help:
|
||||
docs create --help
|
||||
docs edit --help
|
||||
docs placeholders --help
|
||||
`);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Setup script to make the `docs` command available locally after yarn install.
|
||||
* Creates a symlink in node_modules/.bin/docs pointing to scripts/docs-cli.js
|
||||
*/
|
||||
|
||||
import { fileURLToPath } from 'url';
|
||||
import { dirname, join } from 'path';
|
||||
import { existsSync, mkdirSync, symlinkSync, unlinkSync, chmodSync } from 'fs';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = dirname(__filename);
|
||||
const rootDir = join(__dirname, '..');
|
||||
|
||||
const binDir = join(rootDir, 'node_modules', '.bin');
|
||||
const binLink = join(binDir, 'docs');
|
||||
const targetScript = join(rootDir, 'scripts', 'docs-cli.js');
|
||||
|
||||
try {
|
||||
// Ensure node_modules/.bin directory exists
|
||||
if (!existsSync(binDir)) {
|
||||
mkdirSync(binDir, { recursive: true });
|
||||
}
|
||||
|
||||
// Remove existing symlink if it exists
|
||||
if (existsSync(binLink)) {
|
||||
unlinkSync(binLink);
|
||||
}
|
||||
|
||||
// Create symlink
|
||||
symlinkSync(targetScript, binLink, 'file');
|
||||
|
||||
// Ensure the target script is executable
|
||||
chmodSync(targetScript, 0o755);
|
||||
|
||||
console.log('✓ Created local `docs` command in node_modules/.bin/');
|
||||
console.log(' You can now use: npx docs <command>');
|
||||
console.log(' Or add node_modules/.bin to your PATH for direct access');
|
||||
} catch (error) {
|
||||
console.error('Failed to setup local docs command:', error.message);
|
||||
process.exit(1);
|
||||
}
|
||||
|
|
@ -7,6 +7,7 @@ You are analyzing a documentation draft to generate an intelligent file structur
|
|||
**Context file**: `.tmp/scaffold-context.json`
|
||||
|
||||
Read and analyze the context file, which contains:
|
||||
|
||||
- **draft**: The markdown content and any existing frontmatter
|
||||
- **products**: Available InfluxDB products (Core, Enterprise, Cloud, etc.)
|
||||
- **productHints**: Products mentioned or suggested based on content analysis
|
||||
|
|
@ -49,11 +50,12 @@ For each file, create complete frontmatter with:
|
|||
- **weight**: Sequential weight based on siblings
|
||||
- **source**: (for frontmatter-only files) Path to shared content
|
||||
- **related**: 3-5 relevant related articles from `structure.existingPaths`
|
||||
- **alt_links**: Map equivalent pages across products for cross-product navigation
|
||||
- **alt\_links**: Map equivalent pages across products for cross-product navigation
|
||||
|
||||
### 4. Code Sample Considerations
|
||||
|
||||
Based on `versionInfo`:
|
||||
|
||||
- Use version-specific CLI commands (influxdb3, influx, influxctl)
|
||||
- Reference appropriate API endpoints (/api/v3, /api/v2)
|
||||
- Note testing requirements from `conventions.testing`
|
||||
|
|
@ -61,6 +63,7 @@ Based on `versionInfo`:
|
|||
### 5. Style Compliance
|
||||
|
||||
Follow conventions from `conventions.namingRules`:
|
||||
|
||||
- Files: Use lowercase with hyphens (e.g., `manage-databases.md`)
|
||||
- Directories: Use lowercase with hyphens
|
||||
- Shared content: Place in appropriate `/content/shared/` subdirectory
|
||||
|
|
@ -133,4 +136,8 @@ Generate a JSON proposal matching the schema in `scripts/schemas/scaffold-propos
|
|||
4. Generate complete frontmatter for all files
|
||||
5. Save the proposal to `.tmp/scaffold-proposal.json`
|
||||
|
||||
The proposal will be validated and used by `yarn docs:create --proposal .tmp/scaffold-proposal.json` to create the files.
|
||||
The following command validates and creates files from the proposal:
|
||||
|
||||
```bash
|
||||
npx docs create --proposal .tmp/scaffold-proposal.json
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue