From 5f47d3d3a29426412c0f48e4dd7280ff99fdc7d1 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 26 Feb 2026 22:17:31 -0600 Subject: [PATCH] fix: consolidate support URL validation into single script Replace three redundant checks (Vale rule, inline LeftHook grep, standalone script) with one script callable from both LeftHook and CI. - Update check-support-links.sh to accept file args and allow both https://support.influxdata.com and .../s/contactsupport - Add separate LeftHook command replacing inline grep - Add CI step in pr-link-check.yml before Node.js setup - Delete dead SupportLink.yml Vale rule (TokenIgnores strips URLs) - Update DOCS-CONTRIBUTING.md with both allowed URLs --- .ci/scripts/check-support-links.sh | 49 ++++++++++++++++++++++ .github/workflows/pr-link-check.yml | 6 +++ DOCS-CONTRIBUTING.md | 65 ++++++++++++++++++++--------- lefthook.yml | 4 ++ 4 files changed, 104 insertions(+), 20 deletions(-) create mode 100755 .ci/scripts/check-support-links.sh diff --git a/.ci/scripts/check-support-links.sh b/.ci/scripts/check-support-links.sh new file mode 100755 index 0000000000..d6ff3a42db --- /dev/null +++ b/.ci/scripts/check-support-links.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# Check for non-standard InfluxData support links. +# +# Allowed URLs: +# https://support.influxdata.com (Support home) +# https://support.influxdata.com/s/contactsupport (Contact Support) +# +# Usage: +# check-support-links.sh [file ...] +# - With args: check only the given files +# - Without args: check all content/**/*.md + +set -euo pipefail + +# Step 1: find lines containing support.influxdata.com with any path +FIND_PATTERN='https://support\.influxdata\.com/' + +# Step 2: exclude the one allowed path (/s/contactsupport not followed by more path) +ALLOW_PATTERN='https://support\.influxdata\.com/s/contactsupport([^[:alnum:]/]|$)' + +# Run grep on explicit file args or default to find + grep +if [[ $# -gt 0 ]]; then + md_files=() + for f in "$@"; do + [[ -f "$f" && "$f" == *.md ]] && md_files+=("$f") + done + if [[ ${#md_files[@]} -eq 0 ]]; then + echo "No markdown files to check." + exit 0 + fi + MATCHES=$(grep -Hn "$FIND_PATTERN" "${md_files[@]}" || true) +else + MATCHES=$(find content -name '*.md' -type f -print0 \ + | xargs -0 grep -Hn "$FIND_PATTERN" || true) +fi + +# Filter out the allowed contact support URL +MATCHES=$(echo "$MATCHES" | grep -vE "$ALLOW_PATTERN" || true) + +if [[ -n "$MATCHES" ]]; then + echo "$MATCHES" + echo "" + echo "ERROR: Found non-standard support.influxdata.com URLs." + echo "Allowed URLs:" + echo " https://support.influxdata.com" + echo " https://support.influxdata.com/s/contactsupport" + echo "See DOCS-CONTRIBUTING.md for details." + exit 1 +fi diff --git a/.github/workflows/pr-link-check.yml b/.github/workflows/pr-link-check.yml index 43f739b6ec..ae97f8dac8 100644 --- a/.github/workflows/pr-link-check.yml +++ b/.github/workflows/pr-link-check.yml @@ -71,6 +71,12 @@ jobs: echo "No content changes detected in this PR - skipping link check" echo "✅ **No content changes detected** - link check skipped" >> $GITHUB_STEP_SUMMARY + - name: Validate support links + if: steps.detect.outputs.has-changes == 'true' + run: | + echo "${{ steps.detect.outputs.changed-content }}" | tr ' ' '\n' | \ + xargs -r .ci/scripts/check-support-links.sh + - name: Setup Node.js if: steps.detect.outputs.has-changes == 'true' uses: actions/setup-node@v4 diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md index 07f1f6ebed..fc531b0762 100644 --- a/DOCS-CONTRIBUTING.md +++ b/DOCS-CONTRIBUTING.md @@ -1,6 +1,7 @@ # Contributing to InfluxData Documentation + ## Quick Start Ready to contribute? @@ -14,7 +15,7 @@ Ready to contribute? For detailed setup and reference information, see the sections below. ---- +*** ## Legal & Getting Started @@ -27,18 +28,19 @@ What constitutes a "substantial" change is at the discretion of InfluxData docum [Sign the InfluxData CLA](https://www.influxdata.com/legal/cla/) -_**Note:** Typo and broken link fixes are greatly appreciated and do not require signing the CLA._ +***Note:** Typo and broken link fixes are greatly appreciated and do not require signing the CLA.* -_If you're new to contributing or you're looking for an easy update, see [`docs-v2` good-first-issues](https://github.com/influxdata/docs-v2/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue)._ +*If you're new to contributing or you're looking for an easy update, see [`docs-v2` good-first-issues](https://github.com/influxdata/docs-v2/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue).* ### Fork and clone InfluxData Documentation Repository [Fork this repository](https://help.github.com/articles/fork-a-repo/) and [clone it](https://help.github.com/articles/cloning-a-repository/) to your local machine. ---- +*** + ## Development Environment Setup ### Prerequisites @@ -76,9 +78,9 @@ dev dependencies used in pre-commit hooks for linting, syntax-checking, and test Dev dependencies include: - [Lefthook](https://github.com/evilmartians/lefthook): configures and -manages git pre-commit and pre-push hooks for linting and testing Markdown content. + manages git pre-commit and pre-push hooks for linting and testing Markdown content. - [prettier](https://prettier.io/docs/en/): formats code, including Markdown, according to style rules for consistency -- [Cypress]: e2e testing for UI elements and URLs in content +- \[Cypress]: e2e testing for UI elements and URLs in content ### Install Docker @@ -112,11 +114,11 @@ docs-v2 contains a `./.vscode/settings.json` that configures the following exten - Vale: shows linter errors and suggestions in the editor. - YAML Schemas: validates frontmatter attributes. ---- +*** -## Making Changes +## Making Changes ### Style Guidelines @@ -128,7 +130,7 @@ Content follows Google Developer Documentation Style Guide and YouTube API docum Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown). -_Some parts of the documentation, such as `./api-docs`, contain Markdown within YAML and rely on additional tooling._ +*Some parts of the documentation, such as `./api-docs`, contain Markdown within YAML and rely on additional tooling.* #### Semantic line feeds @@ -164,6 +166,23 @@ Save images using the following naming format: `project/version-context-descript For example, `influxdb/2-0-visualizations-line-graph.png` or `influxdb/2-0-tasks-add-new.png`. Specify a version other than 2.0 only if the image is specific to that version. +#### InfluxData Support links + +When linking to InfluxData Support, use one of these URLs: + +```markdown +[InfluxData support](https://support.influxdata.com) +[contact InfluxData support](https://support.influxdata.com/s/contactsupport) +``` + +**Do not use**: + +- `https://support.influxdata.com/` (trailing slash) +- `https://support.influxdata.com/s/login/?ec=302&startURL=%2Fs%2Fcontactsupport` (login redirect) +- Any other `support.influxdata.com` path + +The pre-commit hook will check for and reject non-standard support link formats. + ### Essential Frontmatter Reference Every documentation page includes frontmatter which specifies information about the page. @@ -268,6 +287,7 @@ Documentation audit tools should: 4. Support both single-line and multi-line exclusion lists + ### Common Shortcodes Reference #### Callouts (notes and warnings) @@ -325,7 +345,7 @@ For the complete shortcodes reference with all available shortcodes and usage ex Test shortcodes with working examples in **[content/example.md](content/example.md)**. ---- +*** ### InfluxDB API documentation @@ -336,11 +356,10 @@ InfluxDB API documentation when documentation is deployed. For more information about editing and generating InfluxDB API documentation, see the [API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme). ---- +*** ## Testing & Quality Assurance - Pre-commit hooks run automatically when you commit changes, testing your staged files with Vale, Prettier, Cypress, and Pytest. To skip hooks if needed: ```sh @@ -362,13 +381,14 @@ docker compose run -T vale content/**/*.md For comprehensive testing information, including code block testing, link validation, style linting, and advanced testing procedures, see **[TESTING.md](TESTING.md)**. - ---- +*** + ## Submission Process + ### Commit Guidelines When creating commits, follow these guidelines: @@ -381,6 +401,7 @@ When creating commits, follow these guidelines: - For multiple issues, use comma separation: `closes influxdata/DAR#517, closes influxdata/DAR#518` **Examples:** + ``` fix(enterprise): correct Docker environment variable name for license email fix(influxdb3): correct Docker environment variable and compose examples for monolith @@ -392,7 +413,7 @@ chore(ci): update Vale configuration Push your changes up to your forked repository, then [create a new pull request](https://help.github.com/articles/creating-a-pull-request/). ---- +*** ## Reference Documentation @@ -402,6 +423,7 @@ For detailed reference documentation, see: - **[DOCS-SHORTCODES.md](DOCS-SHORTCODES.md)** - Complete shortcodes reference with usage examples for all available shortcodes + ### Advanced Configuration #### Vale style linting configuration @@ -437,6 +459,7 @@ To add accepted/rejected terms for specific products, configure a style for the To learn more about configuration and rules, see [Vale configuration](https://vale.sh/docs/topics/config). + #### JavaScript in the documentation UI The InfluxData documentation UI uses TypeScript and JavaScript with ES6+ syntax and @@ -453,13 +476,14 @@ If you're adding UI functionality that requires JavaScript, follow these steps: ```html
- ``` + ``` 2. Following the component pattern, create a single-purpose JavaScript module (`assets/js/components/my-component.js`) that exports a single function that receives the component element and initializes it. + 3. In `assets/js/main.js`, import the module and register the component to ensure - the component is initialized on page load. + the component is initialized on page load. ##### Debugging JavaScript @@ -473,7 +497,7 @@ To debug JavaScript code used in the InfluxData documentation UI, choose one of 1. In VS Code, select Run > Start Debugging. 2. Select the "Debug Docs (source maps)" configuration. 3. Click the play button to start the debugger. -5. Set breakpoints in the JavaScript source files--files in the +4. Set breakpoints in the JavaScript source files--files in the `assets/js/ns-hugo-imp:` namespace-- in the VS Code editor or in the Chrome Developer Tools Sources panel: @@ -487,8 +511,9 @@ To debug JavaScript code used in the InfluxData documentation UI, choose one of 1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`. These helpers provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger. + 2. Insert debug statements by calling the helper functions in your code--for example: - + ```js import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js'; @@ -515,4 +540,4 @@ 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. \ No newline at end of file +The debug helpers are designed to be used in development and should not be used in production. diff --git a/lefthook.yml b/lefthook.yml index d822e1dfca..242cd46047 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -24,6 +24,10 @@ pre-commit: fi exit $errors fail_text: "Deprecated markdown patterns found. See messages above for details." + check-support-links: + tags: lint + glob: "content/**/*.md" + run: .ci/scripts/check-support-links.sh {staged_files} eslint-debug-check: glob: "assets/js/*.js" run: yarn eslint {staged_files}