[
https://issues.apache.org/jira/browse/FLINK-39046?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
featzhang updated FLINK-39046:
------------------------------
Summary: [Docs][Kinesis] Incorrect Hugo ref syntax in Kinesis documentation
(was: [docs] Incorrect Hugo ref syntax in Kinesis documentation)
> [Docs][Kinesis] 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
> Priority: Major
>
> 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)
