diff --git a/.ci/remark-lint/package.json b/.ci/remark-lint/package.json index cc6d1d69e..3ba9a210a 100644 --- a/.ci/remark-lint/package.json +++ b/.ci/remark-lint/package.json @@ -3,6 +3,7 @@ "license": "MIT", "devDependencies": { "remark-cli": "12.0.1", + "remark-gfm": "4.0.1", "remark-preset-lint-consistent": "6.0.0", "remark-preset-lint-markdown-style-guide": "6.0.0", "remark-preset-lint-recommended": "7.0.0", diff --git a/.ci/vale/styles/.vale-config/1-Hugo.ini b/.ci/vale/styles/.vale-config/1-Hugo.ini deleted file mode 100644 index 4347ca9e9..000000000 --- a/.ci/vale/styles/.vale-config/1-Hugo.ini +++ /dev/null @@ -1,10 +0,0 @@ -[*.md] -# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) -TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ -(\[.+\]\({{< .+ >}}\)), \ -[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \ -[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s - -# Exclude `{{< myshortcode `This is some HTML, ... >}}` -BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \ -(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}) diff --git a/.husky/_/pre-commit b/.husky/_/pre-commit index 4855f6124..710b28856 100755 --- a/.husky/_/pre-commit +++ b/.husky/_/pre-commit @@ -33,6 +33,9 @@ call_lefthook() then "$dir/node_modules/lefthook/bin/index.js" "$@" + elif go tool lefthook -h >/dev/null 2>&1 + then + go tool lefthook "$@" elif bundle exec lefthook -h >/dev/null 2>&1 then bundle exec lefthook "$@" @@ -42,12 +45,21 @@ call_lefthook() elif pnpm lefthook -h >/dev/null 2>&1 then pnpm lefthook "$@" - elif swift package plugin lefthook >/dev/null 2>&1 + elif swift package lefthook >/dev/null 2>&1 then - swift package --disable-sandbox plugin lefthook "$@" + swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" + elif uv run lefthook -h >/dev/null 2>&1 + then + uv run lefthook "$@" + elif mise exec -- lefthook -h >/dev/null 2>&1 + then + mise exec -- lefthook "$@" + elif devbox run lefthook -h >/dev/null 2>&1 + then + devbox run lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/pre-push b/.husky/_/pre-push index a0d96ef93..17b532e00 100755 --- a/.husky/_/pre-push +++ b/.husky/_/pre-push @@ -33,6 +33,9 @@ call_lefthook() then "$dir/node_modules/lefthook/bin/index.js" "$@" + elif go tool lefthook -h >/dev/null 2>&1 + then + go tool lefthook "$@" elif bundle exec lefthook -h >/dev/null 2>&1 then bundle exec lefthook "$@" @@ -42,12 +45,21 @@ call_lefthook() elif pnpm lefthook -h >/dev/null 2>&1 then pnpm lefthook "$@" - elif swift package plugin lefthook >/dev/null 2>&1 + elif swift package lefthook >/dev/null 2>&1 then - swift package --disable-sandbox plugin lefthook "$@" + swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" + elif uv run lefthook -h >/dev/null 2>&1 + then + uv run lefthook "$@" + elif mise exec -- lefthook -h >/dev/null 2>&1 + then + mise exec -- lefthook "$@" + elif devbox run lefthook -h >/dev/null 2>&1 + then + devbox run lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/.husky/_/prepare-commit-msg b/.husky/_/prepare-commit-msg index 2655902bc..6efab23a3 100755 --- a/.husky/_/prepare-commit-msg +++ b/.husky/_/prepare-commit-msg @@ -33,6 +33,9 @@ call_lefthook() then "$dir/node_modules/lefthook/bin/index.js" "$@" + elif go tool lefthook -h >/dev/null 2>&1 + then + go tool lefthook "$@" elif bundle exec lefthook -h >/dev/null 2>&1 then bundle exec lefthook "$@" @@ -42,12 +45,21 @@ call_lefthook() elif pnpm lefthook -h >/dev/null 2>&1 then pnpm lefthook "$@" - elif swift package plugin lefthook >/dev/null 2>&1 + elif swift package lefthook >/dev/null 2>&1 then - swift package --disable-sandbox plugin lefthook "$@" + swift package --build-path .build/lefthook --disable-sandbox lefthook "$@" elif command -v mint >/dev/null 2>&1 then mint run csjones/lefthook-plugin "$@" + elif uv run lefthook -h >/dev/null 2>&1 + then + uv run lefthook "$@" + elif mise exec -- lefthook -h >/dev/null 2>&1 + then + mise exec -- lefthook "$@" + elif devbox run lefthook -h >/dev/null 2>&1 + then + devbox run lefthook "$@" else echo "Can't find lefthook in PATH" fi diff --git a/.remarkrc.yaml b/.remarkrc.yaml new file mode 100644 index 000000000..e022793fc --- /dev/null +++ b/.remarkrc.yaml @@ -0,0 +1,9 @@ +settings: + bullet: "-" + +plugins: + # GitHub-flavored Markdown support (tables, task lists, strikethrough, etc.) + - remark-gfm + - remark-frontmatter + # Check that markdown is consistent (list items have the same indentation) + - remark-preset-lint-consistent diff --git a/.vale-instructions.ini b/.vale-instructions.ini new file mode 100644 index 000000000..d1ee502b1 --- /dev/null +++ b/.vale-instructions.ini @@ -0,0 +1,13 @@ +StylesPath = .ci/vale/styles + +MinAlertLevel = warning + +# Use general technical writing packages +Packages = write-good + +[*.md] +# Base styles focused on clarity and consistency +BasedOnStyles = Vale, write-good + +# Disable style rules that are too opinionated for instruction files +Vale.Spelling = NO diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md index a505f2a97..cceff8c3c 100644 --- a/DOCS-CONTRIBUTING.md +++ b/DOCS-CONTRIBUTING.md @@ -120,6 +120,10 @@ docs-v2 contains a `./.vscode/settings.json` that configures the following exten ### Style Guidelines +#### Content Guidelines + +Content follows Google Developer Documentation Style Guide and YouTube API documentation patterns with a few InfluxData-specific adaptations. + #### Markdown Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown). diff --git a/compose.yaml b/compose.yaml index fbeb8196c..5d3887a13 100644 --- a/compose.yaml +++ b/compose.yaml @@ -511,17 +511,18 @@ services: remark-lint: container_name: remark-lint build: - context: . + context: . dockerfile: .ci/Dockerfile.remark profiles: - lint volumes: + # Mount repository to /workdir to avoid overwriting /app/ node_modules + # Remark will receive paths like /workdir/content/file.md or /workdir/README.md + # Writable mount allows auto-fixing instruction files (README.md, DOCS-*.md, etc.) - type: bind - source: ./content - target: /app/content - - type: bind - source: ./CONTRIBUTING.md - target: /app/CONTRIBUTING.md + source: . + target: /workdir + read_only: false volumes: test-content: cloud-tmp: diff --git a/content/.remarkrc.yaml b/content/.remarkrc.yaml index 48bb1a365..9b2fee227 100644 --- a/content/.remarkrc.yaml +++ b/content/.remarkrc.yaml @@ -4,6 +4,7 @@ settings: plugins: # Before you can configure plugins for remark here, you need to add them to # the `devDependencies` in the `package.json` file--for CI: `/.ci/app/package.json`. + - remark-gfm - remark-frontmatter - remark-lint-frontmatter-schema - remark-lint-no-shell-dollars diff --git a/lefthook.yml b/lefthook.yml index e528b285f..175fbfd48 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -12,12 +12,43 @@ pre-commit: build-agent-instructions: glob: "data/products.yml" run: yarn build:agent:instructions - # Report linting warnings and errors, don't output files to stdout - lint-markdown: + # Auto-fix markdown formatting for instruction and README files (like prettier) + lint-markdown-instructions: tags: lint - glob: "{README.md,DOCS-*.md,api-docs/README.md,content/*.md}" + glob: "{README.md,*[A-Z]*.md,.github/**/*.md,.claude/**/*.md}" run: | - docker compose run --rm --name remark-lint remark-lint '{staged_files}' + # Prepend /workdir/ to staged files since repository is mounted at /workdir in container + files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g') + docker compose run --rm --name remark-lint remark-lint $files --output --quiet || \ + { echo "⚠️ Remark found formatting issues in instruction files. Automatic formatting applied."; } + stage_fixed: true + # Report markdown formatting issues in content/api-docs without auto-fixing + lint-markdown-content: + tags: lint + glob: "{api-docs/**/*.md,content/**/*.md}" + run: | + # Prepend /workdir/ to staged files since repository is mounted at /workdir in container + files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g') + # Run remark to check for formatting differences (without --output, shows diff in stdout) + # If output differs from input, fail the commit + for file in $files; do + original=$(cat "${file#/workdir/}") + formatted=$(docker compose run --rm --name remark-lint-content remark-lint "$file" 2>/dev/null | tail -n +2) + if [ "$original" != "$formatted" ]; then + echo "❌ Markdown formatting issues in ${file#/workdir/}" + echo " Run: docker compose run --rm remark-lint $file --output" + echo " Or manually fix the formatting to match remark style" + exit 1 + fi + done + echo "✅ All content files are properly formatted" + # Lint instruction and repository documentation files with generic Vale config + lint-instructions: + tags: lint + glob: "{README.md,*[A-Z]*.md,.github/**/*.md,.claude/**/*.md,api-docs/README.md}" + run: '.ci/vale/vale.sh + --config=.vale-instructions.ini + --minAlertLevel=warning {staged_files}' cloud-lint: tags: lint,v2 glob: 'content/influxdb/cloud/*.md'