2.8 KiB

Raw Blame History

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:

Adds { placeholders="PATTERN1|PATTERN2" } attribute to code block fences
Wraps placeholder descriptions with {{% code-placeholder-key %}} shortcodes

Usage

Direct usage

# 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

# Process a file
yarn docs:add-placeholders <file.md>

# Dry run
yarn docs:add-placeholders <file.md> --dry

Example transformations

Before

```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

```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

Finds all code blocks (including indented ones)
Extracts UPPERCASE placeholders
Adds { placeholders="..." } attribute to the fence line
Preserves indentation and language identifiers

Description wrapping

Detects "Replace the following:" sections
Wraps placeholder descriptions matching - **PLACEHOLDER**: description
Preserves indentation and formatting
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

DOCS-SHORTCODES.md - Complete shortcode reference
DOCS-CONTRIBUTING.md - Placeholder conventions and style guidelines

2.8 KiB Raw Blame History