featzhang created FLINK-39046:
---------------------------------
Summary: [docs] Incorrect Hugo ref syntax in Kinesis documentation
Key: FLINK-39046
URL: https://issues.apache.org/jira/browse/FLINK-39046
Project: Flink
Issue Type: Improvement
Components: Connectors / Kinesis
Reporter: featzhang
The Kinesis connector documentation contains incorrect Hugo ref shortcode
syntax when referencing main Flink documentation pages with anchors. This
causes build failures when the documentation is integrated into the main Flink
repository.
h2. Affected Files
* {{docs/content/docs/connectors/datastream/kinesis.md}}
* {{docs/content/docs/connectors/table/kinesis.md}} (potentially, needs
verification)
h2. Current (Incorrect) Syntax
Hugo's {{ref}} shortcode does not support anchors inside the path parameter.
The current documentation uses incorrect syntax:
h3. Line 163 in {{kinesis.md}}
{{This is in line with [Flink best practices](\{{< ref
"docs/ops/production_ready/#set-uuids-for-all-operators" >}}).}}
h3. Line 499 in {{kinesis.md}}
{{The Kinesis Sink provides some metrics through Flink's [metrics system](\{{<
ref "docs/ops/metrics" >}}) to analyze the behavior of the connector. A list of
all exposed metrics may be found [here](\{{<ref
"docs/ops/metrics#kinesis-sink">}}).}}
h2. Expected (Correct) Syntax
Anchors must be placed *outside* the ref shortcode:
h3. Line 163 - Corrected
{{This is in line with [Flink best practices](\{{< ref
"docs/ops/production_ready" >}}#set-uuids-for-all-operators).}}
h3. Line 499 - Corrected
{{The Kinesis Sink provides some metrics through Flink's [metrics system](\{{<
ref "docs/ops/metrics" >}}) to analyze the behavior of the connector. A list of
all exposed metrics may be found [here](\{{<ref
"docs/ops/metrics">}}#kinesis-sink).}}
h2. Hugo Documentation Reference
>From Hugo's documentation on {{ref}} shortcode:
* ✅ Correct: {{{\{< ref "path/to/page" >}}#anchor}}
* ❌ Incorrect: {{{\{< ref "path/to/page#anchor" >}}}}
The anchor fragment must be appended *after* the shortcode closing tag.
h2. Impact
* Causes {{REF_NOT_FOUND}} errors when building Flink documentation
* Breaks documentation integration in CI/CD pipelines
* Requires workaround in main Flink repository
Example error:
{{ERROR [en] REF_NOT_FOUND: Ref "docs/ops/production_ready/":
"/home/vsts/work/1/s/docs/themes/connectors/content/docs/connectors/datastream/kinesis.md:1:1":
page not found}}
h2. Proposed Fix
Update all refs that reference external (main Flink) documentation to use the
correct syntax:
*Pattern to search for:*
{{{\{< ref "docs/(ops|dev)/[^"]*#[^"]*" >}}
\{{<ref "docs/(ops|dev)/[^"]*#[^"]*">}}}}
*Replacement pattern:*
* Extract the path (before {{{}#{}}})
* Extract the anchor (after {{{}#{}}})
* Rewrite as: {{{\{< ref "path" >}}#anchor}}
h2. Checklist
Files to check and fix:
* {{docs/content/docs/connectors/datastream/kinesis.md}} (line 163, 499)
* {{docs/content/docs/connectors/table/kinesis.md}} (if exists)
* {{docs/content.zh/docs/connectors/datastream/kinesis.md}} (Chinese version)
* {{docs/content.zh/docs/connectors/table/kinesis.md}} (Chinese version, if
exists)
* Any other documentation files with cross-references to main Flink docs
h2. Additional Context
This issue affects integration with Apache Flink documentation build. A
temporary workaround has been implemented in the main Flink repository
(apache/flink), but the proper fix should be made here at the source.
*Related:*
* Main Flink workaround PR: [FLINK-39045]
* Hugo ref shortcode docs:
[https://gohugo.io/content-management/cross-references/]
h2. Labels
* Type: Bug
* Component: Documentation
* Priority: Medium
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
