From 3e4864a836673912bbc8c945afd4c02bb7097540 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Mon, 22 Sep 2025 10:50:15 -0500 Subject: [PATCH] Instructions files cleanup: - Follow Copilot guidelines for naming instructions files according to the directory they apply to - Copy instructions files as CLAUDE.md to the relevant directory. - Update placeholder instructions - Optimize Copilot instructions - Remove Claude instructions and reference the Copilot instructions file instead TODO: update the commit hook script to correctly generate and place the files. --- .github/copilot-instructions.md | 326 +++++------------- .github/instructions/api-docs.instructions.md | 28 ++ .github/instructions/assets.instructions.md | 55 +++ ...nstructions.md => content.instructions.md} | 28 +- .../instructions/contributing.instructions.md | 118 +------ ...nfluxdb3-code-placeholders.instructions.md | 100 ------ .../shortcodes-reference.instructions.md | 112 ++++-- CLAUDE.md | 10 - api-docs/CLAUDE.md | 2 + assets/CLAUDE.md | 4 + content/CLAUDE.md | 2 + 11 files changed, 299 insertions(+), 486 deletions(-) create mode 100644 .github/instructions/api-docs.instructions.md create mode 100644 .github/instructions/assets.instructions.md rename .github/instructions/{frontmatter-reference.instructions.md => content.instructions.md} (90%) delete mode 100644 .github/instructions/influxdb3-code-placeholders.instructions.md create mode 100644 api-docs/CLAUDE.md create mode 100644 assets/CLAUDE.md create mode 100644 content/CLAUDE.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4a541203f..e7b966fa5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,6 +1,17 @@ # InfluxData Documentation Repository (docs-v2) -Always follow these instructions first and fallback to additional search and context gathering only when the information provided here is incomplete or found to be in error. +This is the primary instruction file for working with the InfluxData documentation site. +For detailed information on specific topics, refer to the specialized instruction files in `.github/instructions/`. + +## Quick Reference + +| Task | Command | Time | Details | +|------|---------|------|---------| +| Install | `CYPRESS_INSTALL_BINARY=0 yarn install` | ~4s | Skip Cypress for CI | +| Build | `npx hugo --quiet` | ~75s | NEVER CANCEL | +| Dev Server | `npx hugo server` | ~92s | Port 1313 | +| Test All | `yarn test:codeblocks:all` | 15-45m | NEVER CANCEL | +| Lint | `yarn lint` | ~1m | Pre-commit checks | ## Working Effectively @@ -8,139 +19,39 @@ Always follow these instructions first and fallback to additional search and con Be a critical thinking partner, provide honest feedback, and identify potential issues. -### Bootstrap, Build, and Test the Repository +### Setup Steps -Execute these commands in order to set up a complete working environment: +1. Install dependencies (see Quick Reference table above) +2. Build the static site +3. Start development server at http://localhost:1313/ +4. Alternative: Use `docker compose up local-dev` if local setup fails -1. **Install Node.js dependencies** (takes ~4 seconds): +### Testing - ```bash - # Skip Cypress binary download due to network restrictions in CI environments - CYPRESS_INSTALL_BINARY=0 yarn install - ``` +For comprehensive testing procedures, see **[TESTING.md](../TESTING.md)**. -2. **Build the static site** (takes ~75 seconds, NEVER CANCEL - set timeout to 180+ seconds): +**Quick reference** (NEVER CANCEL long-running tests): +- **Code blocks**: `yarn test:codeblocks:all` (15-45 minutes) +- **Links**: `yarn test:links` (1-5 minutes, requires link-checker binary) +- **Style**: `docker compose run -T vale content/**/*.md` (30-60 seconds) +- **Pre-commit**: `yarn lint` (or skip with `--no-verify`) - ```bash - npx hugo --quiet - ``` +### Validation -3. **Start the development server** (builds in ~92 seconds, NEVER CANCEL - set timeout to 150+ seconds): - - ```bash - npx hugo server --bind 0.0.0.0 --port 1313 - ``` - - - Access at: http://localhost:1313/ - - Serves 5,359+ pages and 441 static files - - Auto-rebuilds on file changes - -4. **Alternative Docker development setup** (use if local Hugo fails): - ```bash - docker compose up local-dev - ``` - **Note**: May fail in restricted network environments due to Alpine package manager issues. - -### Testing (CRITICAL: NEVER CANCEL long-running tests) - -#### Code Block Testing (takes 5-15 minutes per product, NEVER CANCEL - set timeout to 30+ minutes): +Test these after changes: ```bash -# Build test environment first (takes ~30 seconds, may fail due to network restrictions) -docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest . - -# Test all products (takes 15-45 minutes total) -yarn test:codeblocks:all - -# Test specific products -yarn test:codeblocks:cloud -yarn test:codeblocks:v2 -yarn test:codeblocks:telegraf -``` - -#### Link Validation (takes 1-5 minutes): - -Runs automatically on pull requests. -Requires the **link-checker** binary from the repo release artifacts. - -```bash -# Test specific files/products (faster) -# JSON format is required for accurate reporting -link-checker map content/influxdb3/core/**/*.md \ -| link-checker check \ - --config .ci/link-checker/production.lycherc.toml - --format json -``` - -#### Style Linting (takes 30-60 seconds): - -```bash -# Basic Vale linting -docker compose run -T vale content/**/*.md - -# Product-specific linting with custom configurations -docker compose run -T vale --config=content/influxdb3/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb3/cloud-dedicated/**/*.md -``` - -#### JavaScript and CSS Linting (takes 5-10 seconds): - -```bash -yarn eslint assets/js/**/*.js -yarn prettier --check "**/*.{css,js,ts,jsx,tsx}" -``` - -### Pre-commit Hooks (automatically run, can be skipped if needed): - -```bash -# Run all pre-commit checks manually -yarn lint - -# Skip pre-commit hooks if necessary (not recommended) -git commit -m "message" --no-verify -``` - -## Validation Scenarios - -Always test these scenarios after making changes to ensure full functionality: - -### 1. Documentation Rendering Test - -```bash -# Start Hugo server -npx hugo server --bind 0.0.0.0 --port 1313 - -# Verify key pages load correctly (200 status) +# 1. Server renders pages (check 200 status) curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb3/core/ -curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/influxdb/v2/ -curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/telegraf/v1/ -# Verify content contains expected elements -curl -s http://localhost:1313/influxdb3/core/ | grep -i "influxdb" -``` +# 2. Build outputs exist (~529MB) +npx hugo --quiet && du -sh public/ -### 2. Build Output Validation - -```bash -# Verify build completes successfully -npx hugo --quiet - -# Check build output exists and has reasonable size (~529MB) -ls -la public/ -du -sh public/ - -# Verify key files exist -file public/index.html -file public/influxdb3/core/index.html -``` - -### 3. Shortcode and Formatting Test - -```bash -# Test shortcode examples page +# 3. Shortcodes work yarn test:links content/example.md ``` -## Repository Structure and Key Locations +## Repository Structure ### Content Organization @@ -151,132 +62,60 @@ yarn test:links content/example.md - **Shared content**: `/content/shared/` - **Examples**: `/content/example.md` (comprehensive shortcode reference) -### Configuration Files +### Key Files -- **Hugo config**: `/config/_default/` -- **Package management**: `package.json`, `yarn.lock` -- **Docker**: `compose.yaml`, `Dockerfile.pytest` -- **Git hooks**: `lefthook.yml` -- **Testing**: `cypress.config.js`, `pytest.ini` (in test directories) -- **Linting**: `.vale.ini`, `.prettierrc.yaml`, `eslint.config.js` - -### Build and Development - -- **Hugo binary**: Available via `npx hugo` (version 0.148.2+) -- **Static assets**: `/assets/` (JavaScript, CSS, images) -- **Build output**: `/public/` (generated, ~529MB) -- **Layouts**: `/layouts/` (Hugo templates) -- **Data files**: `/data/` (YAML/JSON data for templates) +- **Config**: `/config/_default/`, `package.json`, `compose.yaml`, `lefthook.yml` +- **Testing**: `cypress.config.js`, `pytest.ini`, `.vale.ini` +- **Assets**: `/assets/` (JS, CSS), `/layouts/` (templates), `/data/` (YAML/JSON) +- **Build output**: `/public/` (~529MB, gitignored) ## Technology Stack -- **Static Site Generator**: Hugo (0.148.2+ extended) -- **Package Manager**: Yarn (1.22.22+) with Node.js (20.19.4+) -- **Testing Framework**: - - Pytest with pytest-codeblocks (for code examples) - - Cypress (for E2E tests) - - influxdata/docs-link-checker (for link validation) - - Vale (for style and writing guidelines) -- **Containerization**: Docker with Docker Compose -- **Linting**: ESLint, Prettier, Vale -- **Git Hooks**: Lefthook +- **Hugo** (0.148.2+ extended) - Static site generator +- **Node.js/Yarn** (20.19.4+/1.22.22+) - Package management +- **Testing**: Pytest, Cypress, link-checker, Vale +- **Tools**: Docker, ESLint, Prettier, Lefthook -## Common Tasks and Build Times +## Common Issues -### Network Connectivity Issues +### Network Restrictions +Commands that may fail in restricted environments: +- Docker builds (external repos) +- `docker compose up local-dev` (Alpine packages) +- Cypress installation (use `CYPRESS_INSTALL_BINARY=0`) -In restricted environments, these commands may fail due to external dependency downloads: - -- `docker build -t influxdata/docs-pytest:latest -f Dockerfile.pytest .` (InfluxData repositories, HashiCorp repos) -- `docker compose up local-dev` (Alpine package manager) -- Cypress binary installation (use `CYPRESS_INSTALL_BINARY=0`) - -Document these limitations but proceed with available functionality. - -### Validation Commands for CI - -Always run these before committing changes: +### Pre-commit Validation ```bash -# Format and lint code +# Quick validation before commits yarn prettier --write "**/*.{css,js,ts,jsx,tsx}" yarn eslint assets/js/**/*.js - -# Test Hugo build npx hugo --quiet - -# Test development server startup -timeout 150 npx hugo server --bind 0.0.0.0 --port 1313 & -sleep 120 -curl -s -o /dev/null -w "%{http_code}" http://localhost:1313/ -pkill hugo ``` -## Key Projects in This Codebase +## Documentation Coverage -1. **InfluxDB 3 Documentation** (Core, Enterprise, Clustered, Cloud Dedicated, Cloud Serverless, and InfluxDB 3 plugins for Core and Enterprise) -2. **InfluxDB 3 Explorer** (UI) -3. **InfluxDB v2 Documentation** (OSS and Cloud) -3. **InfuxDB v1 Documentation** (OSS and Enterprise) -4. **Telegraf Documentation** (agent and plugins) -5. **Supporting Tools Documentation** (Kapacitor, Chronograf, Flux) -6. **API Reference Documentation** (`/api-docs/`) -7. **Shared Documentation Components** (`/content/shared/`) +- **InfluxDB 3**: Core, Enterprise, Cloud (Dedicated/Serverless), Clustered, Explorer, plugins +- **InfluxDB v2/v1**: OSS, Cloud, Enterprise +- **Tools**: Telegraf, Kapacitor, Chronograf, Flux +- **API Reference**: All InfluxDB editions -## Important Locations for Frequent Tasks +## Content Guidelines -- **Shortcode reference**: `/content/example.md` -- **Contributing guide**: `CONTRIBUTING.md` -- **Testing guide**: `TESTING.md` -- **Product configurations**: `/data/products.yml` -- **Vale style rules**: `/.ci/vale/styles/` -- **GitHub workflows**: `/.github/workflows/` -- **Test scripts**: `/test/scripts/` -- **Hugo layouts and shortcodes**: `/layouts/` -- **CSS/JS assets**: `/assets/` +- **Product versions**: `/data/products.yml` +- **Query languages**: SQL, InfluxQL, Flux (per product version) +- **Site**: https://docs.influxdata.com -## Content Guidelines and Style +### Writing Documentation -### Documentation Structure +For detailed guidelines, see: +- **Frontmatter**: `.github/instructions/content.instructions.md` +- **Shortcodes**: `.github/instructions/shortcodes-reference.instructions.md` +- **Contributing**: `.github/instructions/contributing.instructions.md` -- **Product version data**: `/data/products.yml` -- **Query Languages**: SQL, InfluxQL, Flux (use appropriate language per product version) -- **Documentation Site**: https://docs.influxdata.com -- **Framework**: Hugo static site generator +### Code Examples -### Style Guidelines - -- Follow Google Developer Documentation style guidelines -- Use semantic line feeds (one sentence per line) -- Format code examples to fit within 80 characters -- Use long options in command line examples (`--option` instead of `-o`) -- Use GitHub callout syntax for notes and warnings -- Image naming: `project/version-context-description.png` - -### Markdown and Shortcodes - -Include proper frontmatter for all content pages: - -```yaml -title: # Page title (h1) -seotitle: # SEO title -description: # SEO description -menu: - product_version: -weight: # Page order (1-99, 101-199, etc.) -``` - -Key shortcodes (see `/content/example.md` for full reference): - -- Notes/warnings (GitHub syntax): `> [!Note]`, `> [!Warning]` -- Tabbed content: `{{< tabs-wrapper >}}`, `{{% tabs %}}`, `{{% tab-content %}}` -- Code examples: `{{< code-tabs-wrapper >}}`, `{{% code-tabs %}}`, `{{% code-tab-content %}}` -- Required elements: `{{< req >}}` -- API endpoints: `{{< api-endpoint >}}` - -### Code Examples and Testing - -Provide complete, working examples with pytest annotations: +Use pytest annotations for testable examples: ```python print("Hello, world!") @@ -288,21 +127,32 @@ print("Hello, world!") Hello, world! ``` -## Troubleshooting Common Issues +## Troubleshooting -1. **"Pytest collected 0 items"**: Use `python` (not `py`) for code block language identifiers -2. **Hugo build errors**: Check `/config/_default/` for configuration issues -3. **Docker build failures**: Expected in restricted networks - document and continue with local Hugo -4. **Cypress installation failures**: Use `CYPRESS_INSTALL_BINARY=0 yarn install` -5. **Link validation slow**: Use file-specific testing: `yarn test:links content/specific-file.md` -6. **Vale linting errors**: Check `.ci/vale/styles/config/vocabularies` for accepted/rejected terms +| Issue | Solution | +|-------|----------| +| Pytest collected 0 items | Use `python` not `py` for language identifier | +| Hugo build errors | Check `/config/_default/` | +| Docker build fails | Expected in restricted networks - use local Hugo | +| Cypress install fails | Use `CYPRESS_INSTALL_BINARY=0 yarn install` | +| Link validation slow | Test specific files: `yarn test:links content/file.md` | +| Vale errors | Check `.ci/vale/styles/config/vocabularies` | -## Additional Instruction Files +## Specialized Instructions -For specific workflows and content types, also refer to: +For detailed information on specific topics: -- **InfluxDB 3 code placeholders**: `.github/instructions/influxdb3-code-placeholders.instructions.md` -- **Contributing guidelines**: `.github/instructions/contributing.instructions.md` -- **Content-specific instructions**: Check `.github/instructions/` directory +| Topic | File | Description | +|-------|------|-------------| +| **Content** | [content.instructions.md](instructions/content.instructions.md) | Frontmatter, metadata, page structure | +| **Shortcodes** | [shortcodes-reference.instructions.md](instructions/shortcodes-reference.instructions.md) | All available Hugo shortcodes | +| **Contributing** | [contributing.instructions.md](instructions/contributing.instructions.md) | Style guide, workflow, CLA | +| **API Docs** | [api-docs.instructions.md](instructions/api-docs.instructions.md) | OpenAPI spec management | +| **Testing** | [TESTING.md](../TESTING.md) | Comprehensive testing procedures | +| **Assets** | [assets.instructions.md](instructions/assets.instructions.md) | JavaScript and CSS development | -Remember: This is a large documentation site with complex build processes. Patience with build times is essential, and NEVER CANCEL long-running operations. +## Important Notes + +- This is a large site (5,359+ pages) with complex build processes +- **NEVER CANCEL** long-running operations (Hugo builds, tests) +- Set appropriate timeouts: Hugo build (180s+), tests (30+ minutes) diff --git a/.github/instructions/api-docs.instructions.md b/.github/instructions/api-docs.instructions.md new file mode 100644 index 000000000..96fdfa1b9 --- /dev/null +++ b/.github/instructions/api-docs.instructions.md @@ -0,0 +1,28 @@ +--- +applyTo: "api-docs/**/*.md, layouts/**/*.html" +--- + +# InfluxDB API documentation + +To edit the API reference documentation, edit the YAML files in `/api-docs`. + +InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full +InfluxDB API documentation when documentation is deployed. +Redoc generates HTML documentation using the InfluxDB `swagger.yml`. +For more information about generating InfluxDB API documentation, see the +[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). + +## Generate API documentation locally + +From `api-docs` directory: + +1. Install dependencies. To generate the API documentation locally, you need to have [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/getting-started/install) installed. + ```sh + yarn install + ``` + +2. Run the script to generate the API documentation. + + ```sh + generate-api-docs.sh + ``` \ No newline at end of file diff --git a/.github/instructions/assets.instructions.md b/.github/instructions/assets.instructions.md new file mode 100644 index 000000000..6eb06fe8f --- /dev/null +++ b/.github/instructions/assets.instructions.md @@ -0,0 +1,55 @@ +--- +applyTo: "assets/**/*.md, layouts/**/*.html" +--- + +## JavaScript in the documentation UI + +The InfluxData documentation UI uses JavaScript with ES6+ syntax and +`assets/js/main.js` as the entry point to import modules from. + + +1. In your HTML file, add a `data-component` attribute to the element that will + encapsulate the UI feature and use the JavaScript module. + + ```html +
+ ``` + +2. In `assets/js/main.js`, import your module and initialize it on the element. + +## Debugging helpers for JavaScript + +In your JavaScript module, import the debug helpers from `assets/js/utils/debug-helpers.js`. + +```js + import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; + + const data = debugInspect(someData, 'Data'); + debugLog('Processing data', 'myFunction'); + + function processData() { + // Add a breakpoint that works with DevTools + debugBreak(); + + // Your existing code... + } + ``` + +## Debugging with VS Code + +1. Start Hugo in development mode--for example: + + ```bash + yarn hugo server + ``` + +2. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. + +Your system uses the configuration in `launch.json` to launch the site in Chrome +and attach the debugger to the Developer Tools console. + +Make sure to remove the debug statements before merging your changes. +The debug helpers are designed to be used in development and should not be used in production. + +_See full CONTRIBUTING.md for complete details._ + diff --git a/.github/instructions/frontmatter-reference.instructions.md b/.github/instructions/content.instructions.md similarity index 90% rename from .github/instructions/frontmatter-reference.instructions.md rename to .github/instructions/content.instructions.md index 8ab4df618..3467792cd 100644 --- a/.github/instructions/frontmatter-reference.instructions.md +++ b/.github/instructions/content.instructions.md @@ -2,11 +2,23 @@ applyTo: "content/**/*.md, layouts/**/*.html" --- -### Complete Frontmatter Reference +## Frontmatter Requirements -Every documentation page includes frontmatter which specifies information about the page. +Documentation pages include frontmatter which specifies information about the page. +Include proper frontmatter for pages in `/content/`, except `/content/shared/`. Frontmatter populates variables in page templates and the site's navigation menu. +```yaml +title: # Page title (h1) +seotitle: # SEO title +description: # SEO description +menu: + product_version: +weight: # Page order (1-99, 101-199, etc.) +``` + +### Complete Frontmatter Reference + ```yaml title: # Title of the page used in the page's h1 seotitle: # Page title used in the html title and used in search engine results @@ -196,3 +208,15 @@ When building shared content, use the `show-in` and `hide-in` shortcodes to show or hide blocks of content based on the current InfluxDB product/version. For more information, see [show-in](#show-in) and [hide-in](#hide-in). +#### Shortcodes in Markdown files + +For the complete shortcodes reference, see `/.github/instructions/shortcodes-reference.instructions.md`. + +### Style Guidelines + +- Follow Google Developer Documentation style guidelines +- Use semantic line feeds (one sentence per line) +- Format code examples to fit within 80 characters +- Use long options in command line examples (`--option` instead of `-o`) +- Use GitHub callout syntax for notes and warnings +- Image naming: `project/version-context-description.png` \ No newline at end of file diff --git a/.github/instructions/contributing.instructions.md b/.github/instructions/contributing.instructions.md index f80ec35d0..80a4715d6 100644 --- a/.github/instructions/contributing.instructions.md +++ b/.github/instructions/contributing.instructions.md @@ -55,7 +55,6 @@ For the linting and tests to run, you need to install: - **Docker**: For running Vale linter and code block tests - **VS Code extensions** (optional): For enhanced editing experience - ```sh git commit -m "" --no-verify ``` @@ -82,7 +81,6 @@ _Some parts of the documentation, such as `./api-docs`, contain Markdown within #### Semantic line feeds - ```diff -Data is taking off. This data is time series. You need a database that specializes in time series. You should check out InfluxDB. +Data is taking off. This data is time series. You need a database that specializes in time series. You need InfluxDB. @@ -91,81 +89,20 @@ _Some parts of the documentation, such as `./api-docs`, contain Markdown within ### Essential Frontmatter Reference - ```yaml title: # Title of the page used in the page's h1 description: # Page description displayed in search engine results # ... (see full CONTRIBUTING.md for complete example) ``` - -_See full CONTRIBUTING.md for complete details._ - -#### Notes and warnings - -```md -> [!Note] -> Insert note markdown content here. - -> [!Warning] -> Insert warning markdown content here. - -> [!Caution] -> Insert caution markdown content here. - -> [!Important] -> Insert important markdown content here. - -> [!Tip] -> Insert tip markdown content here. -``` - -#### Tabbed content - -```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 >}} -``` - -#### Required elements - -```md -{{< req >}} -{{< req type="key" >}} - -- {{< req "\*" >}} **This element is required** -- {{< req "\*" >}} **This element is also required** -- **This element is NOT required** -``` - -For the complete shortcodes reference with all available shortcodes, see [Complete Shortcodes Reference](#complete-shortcodes-reference). - ---- +See content.instructions.md for more details. ### InfluxDB API documentation docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory. To edit the API documentation, edit the YAML files in `/api-docs`. -InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full -InfluxDB API documentation when documentation is deployed. -Redoc generates HTML documentation using the InfluxDB `swagger.yml`. -For more information about generating InfluxDB API documentation, see the -[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). +See api-docs.instructions.md for more details. --- @@ -173,7 +110,7 @@ For more information about generating InfluxDB API documentation, see the For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. -### Quick Testing Reference +### Testing Code Blocks ```bash # Test code blocks @@ -181,9 +118,6 @@ yarn test:codeblocks:all # Test links yarn test:links content/influxdb3/core/**/*.md - -# Run style linting -docker compose run -T vale content/**/*.md ``` Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed: @@ -215,16 +149,15 @@ chore(ci): update Vale configuration ## Reference Sections - _See full CONTRIBUTING.md for complete details._ ### Complete Frontmatter Reference -_For the complete Complete Frontmatter Reference reference, see frontmatter-reference.instructions.md._ +_For the complete Complete Frontmatter Reference reference, see content.instructions.md._ ### Complete Shortcodes Reference -_For the complete Complete Shortcodes Reference reference, see shortcodes-reference.instructions.md._ +_For the complete Complete Shortcodes Reference reference, see content.instructions.md._ #### Vale style linting configuration @@ -236,52 +169,11 @@ docs-v2 includes Vale writing style linter configurations to enforce documentati docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini --minAlertLevel=error content/influxdb/cloud-dedicated/write-data/**/*.md ``` - - **Error**: - **Warning**: General style guide rules and best practices - **Suggestion**: Style preferences that may require refactoring or updates to an exceptions list #### Configure style rules - -_See full CONTRIBUTING.md for complete details._ - -#### JavaScript in the documentation UI - -The InfluxData documentation UI uses JavaScript with ES6+ syntax and -`assets/js/main.js` as the entry point to import modules from - - -1. In your HTML file, add a `data-component` attribute to the element that - -# ... (see full CONTRIBUTING.md for complete example) -```js - import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; - - const data = debugInspect(someData, 'Data'); - debugLog('Processing data', 'myFunction'); - - function processData() { - // Add a breakpoint that works with DevTools - debugBreak(); - - // Your existing code... - } - ``` - -3. Start Hugo in development mode--for example: - - ```bash - yarn hugo server - ``` - -4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration. - -Your system uses the configuration in `launch.json` to launch the site in Chrome -and attach the debugger to the Developer Tools console. - -Make sure to remove the debug statements before merging your changes. -The debug helpers are designed to be used in development and should not be used in production. - _See full CONTRIBUTING.md for complete details._ diff --git a/.github/instructions/influxdb3-code-placeholders.instructions.md b/.github/instructions/influxdb3-code-placeholders.instructions.md deleted file mode 100644 index 1c341e2d1..000000000 --- a/.github/instructions/influxdb3-code-placeholders.instructions.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -mode: 'edit' -applyTo: "content/{influxdb3/core,influxdb3/enterprise,shared/influxdb3*}/**" ---- -## Best Practices - -- Use UPPERCASE for placeholders to make them easily identifiable -- Don't use pronouns in placeholders (e.g., "your", "this") -- List placeholders in the same order they appear in the code -- Provide clear descriptions including: -- - Expected data type or format -- - Purpose of the value -- - Any constraints or requirements -- Mark optional placeholders as "Optional:" in their descriptions -- Placeholder key descriptions should fit the context of the code snippet -- Include examples for complex formats - -## Writing Placeholder Descriptions - -Descriptions should follow consistent patterns: - -1. **Admin Authentication tokens**: - - Recommended: "a {{% token-link "admin" %}} for your {{< product-name >}} instance" - - Avoid: "your token", "the token", "an authorization token" -2. **Database resource tokens**: - - 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]" - - Avoid: "your database", "the database name" -4. **Conditional content**: - - Use `{{% show-in "enterprise" %}}` for content specific to enterprise versions - - Example: "your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}" - -## Common placeholders for InfluxDB 3 - -- `AUTH_TOKEN`: your {{% token-link %}} -- `DATABASE_NAME`: the database to use -- `TABLE_NAME`: Name of the table/measurement to query or write to -- `NODE_ID`: Node ID for a specific node in a cluster -- `CLUSTER_ID`: Cluster ID for a specific cluster -- `HOST`: InfluxDB server hostname or URL -- `PORT`: InfluxDB server port (typically 8181) -- `QUERY`: SQL or InfluxQL query string -- `LINE_PROTOCOL`: Line protocol data for writes -- `PLUGIN_FILENAME`: Name of plugin file to use -- `CACHE_NAME`: Name for a new or existing cache - -## Hugo shortcodes in Markdown - -**Syntax**: - -- Use the `placeholders` code block attribute to define placeholder patterns: - ``` { placeholders="" } - function sampleCode () {}; - ``` -**Old (deprecated) syntax**: - -- `{{% code-placeholders "PLACEHOLDER1|PLACEHOLDER2" %}}` -- `{{% /code-placeholders %}}` - -**Define a placeholder key (typically following the example)**: - -- `{{% code-placeholder-key %}}`: Use this shortcode to define a placeholder key -- `{{% /code-placeholder-key %}}`: Use this shortcode to close the key name -- Follow with a description - -## Language-Specific Placeholder Formatting - -- **Bash/Shell**: Use uppercase variables with no quotes or prefix - ```bash { placeholders="DATABASE_NAME" } - --database DATABASE_NAME - ``` -- Python: Use string literals with quotes - ```python { placeholders="DATABASE_NAME" } - database_name='DATABASE_NAME' - ``` -- JSON: Use key-value pairs with quotes - ```json { placeholders="DATABASE_NAME" } - { - "database": "DATABASE_NAME" - } - ``` - -## Real-World Examples from Documentation - -### InfluxDB CLI Commands -This pattern appears frequently in CLI documentation: - -```bash { placeholders="DATABASE_NAME|AUTH_TOKEN" } -influxdb3 write \ - --database DATABASE_NAME \ - --token AUTH_TOKEN \ - --precision ns -{{% /code-placeholders %}} - -Replace the following placeholders with your values: - -{{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to write to -{{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}} \ No newline at end of file diff --git a/.github/instructions/shortcodes-reference.instructions.md b/.github/instructions/shortcodes-reference.instructions.md index 098ae1e07..21dad7f89 100644 --- a/.github/instructions/shortcodes-reference.instructions.md +++ b/.github/instructions/shortcodes-reference.instructions.md @@ -4,19 +4,8 @@ applyTo: "content/**/*.md, layouts/**/*.html" ### Complete Shortcodes Reference -#### 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 %}} -``` +influxdata/docs-v2 uses a variety of custom Hugo shortcodes to add functionality. +For more usage examples, see the shortcode test page at `/content/example.md`. #### Product data @@ -1161,22 +1150,65 @@ Supported argument values: {{< influxdb/host "serverless" >}} ``` -##### User-populated placeholders +#### Placeholders in code samples -Use the `code-placeholders` shortcode to format placeholders -as text fields that users can populate with their own values. -The shortcode takes a regular expression for matching placeholder names. -Use the `code-placeholder-key` shortcode to format the placeholder names in -text that describes the placeholder--for example: + ##### Best Practices -```markdown -{{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}} -```sh +- Use UPPERCASE for placeholders to make them easily identifiable +- Don't use pronouns in placeholders (e.g., "your", "this") +- List placeholders in the same order they appear in the code +- Provide clear descriptions including: +- - Expected data type or format +- - Purpose of the value +- - Any constraints or requirements +- Mark optional placeholders as "Optional:" in their descriptions +- Placeholder key descriptions should fit the context of the code snippet +- Include examples for complex formats + +##### Writing Placeholder Descriptions + +Descriptions should follow consistent patterns: + +1. **Admin Authentication tokens**: + - Recommended: "a {{% token-link "admin" %}} for your {{< product-name >}} instance" + - Avoid: "your token", "the token", "an authorization token" +2. **Database resource tokens**: + - 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]" + - Avoid: "your database", "the database name" +4. **Conditional content**: + - Use `{{% show-in "enterprise" %}}` for content specific to enterprise versions + - Example: "your {{% token-link "database" %}}{{% show-in "enterprise" %}} with permission to query the specified database{{% /show-in %}}" + +##### Common placeholders for InfluxDB 3 + +- `AUTH_TOKEN`: your {{% token-link %}} +- `DATABASE_NAME`: the database to use +- `TABLE_NAME`: Name of the table/measurement to query or write to +- `NODE_ID`: Node ID for a specific node in a cluster +- `CLUSTER_ID`: Cluster ID for a specific cluster +- `HOST`: InfluxDB server hostname or URL +- `PORT`: InfluxDB server port (typically 8181) +- `QUERY`: SQL or InfluxQL query string +- `LINE_PROTOCOL`: Line protocol data for writes +- `PLUGIN_FILENAME`: Name of plugin file to use +- `CACHE_NAME`: Name for a new or existing cache + +##### Syntax + +- `{ placeholders }`: 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 + +##### Example usage + +```sh { placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" } curl --request POST http://localhost:8086/write?db=DATABASE_NAME \ --header "Authorization: Token API_TOKEN" \ --data-binary @path/to/line-protocol.txt ``` -{{% /code-placeholders %}} Replace the following: @@ -1184,6 +1216,40 @@ Replace the following: - {{% code-placeholder-key %}}`USERNAME`{{% /code-placeholder-key %}}: your [InfluxDB 1.x username](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) - {{% code-placeholder-key %}}`PASSWORD_OR_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB 1.x password or InfluxDB API token](/influxdb/v2/reference/api/influxdb-1x/#manage-credentials) - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/) + +**Old (deprecated) syntax**: + +Replace the following syntax with the new syntax shown above. + +- `{{% code-placeholders "PLACEHOLDER1|PLACEHOLDER2" %}}` +- `{{% /code-placeholders %}}` + +## Notes and warnings + +```md +> [!Note] +> Insert note markdown content here. + +> [!Warning] +> Insert warning markdown content here. + +> [!Caution] +> Insert caution markdown content here. + +> [!Important] +> Insert important markdown content here. + +> [!Tip] +> Insert tip markdown content here. ``` +## Required elements +```md +{{< req >}} +{{< req type="key" >}} + +- {{< req "\*" >}} **This element is required** +- {{< req "\*" >}} **This element is also required** +- **This element is NOT required** +``` \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index d606868cc..0fc7b5866 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,15 +24,5 @@ formatting, and commonly used shortcodes. See @TESTING.md for comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures. -See @.github/instructions/shortcodes-reference.instructions.md for detailed -information about shortcodes used in this project. - -See @.github/instructions/frontmatter-reference.instructions.md for detailed -information about frontmatter used in this project. - -See @.github/instructions/influxdb3-code-placeholders.instructions.md for using -placeholders in code samples and CLI commands. - See @api-docs/README.md for information about the API reference documentation, how to generate it, and how to contribute to it. - diff --git a/api-docs/CLAUDE.md b/api-docs/CLAUDE.md new file mode 100644 index 000000000..db2650db8 --- /dev/null +++ b/api-docs/CLAUDE.md @@ -0,0 +1,2 @@ +# API reference documentation instructions +See @.github/instructions/api-docs.instructions.md for the complete API reference docs editing guidelines and instructions for generating pages locally. diff --git a/assets/CLAUDE.md b/assets/CLAUDE.md new file mode 100644 index 000000000..c43d40ff0 --- /dev/null +++ b/assets/CLAUDE.md @@ -0,0 +1,4 @@ +## JavaScript, TypeScript, and CSS in the documentation UI + +See @.github/instructions/assets.instructions.md for the complete JavaScript, TypeScript, and SASS (CSS) development guidelines. + diff --git a/content/CLAUDE.md b/content/CLAUDE.md new file mode 100644 index 000000000..902b89680 --- /dev/null +++ b/content/CLAUDE.md @@ -0,0 +1,2 @@ + # Frontmatter and Content Instructions + See @.github/instructions/content.instructions.md for the complete frontmatter reference and content guidelines. \ No newline at end of file