- 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.
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -801,9 +801,71 @@ Descriptions should follow consistent 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)
|
||||
|
|
|
|||
39
README.md
39
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,9 +56,9 @@ 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
|
||||
|
||||
|
|
@ -58,7 +79,13 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report-
|
|||
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).
|
||||
|
||||
|
|
@ -71,6 +98,7 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report-
|
|||
```sh
|
||||
npx hugo server
|
||||
```
|
||||
|
||||
5. View the docs at [localhost:1313](http://localhost:1313).
|
||||
|
||||
### Alternative: Use docker compose
|
||||
|
|
@ -84,4 +112,5 @@ including our GPG key, can be found at https://www.influxdata.com/how-to-report-
|
|||
```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