[jira] [Created] (FLINK-39045) [docs] Add automatic fix for Hugo ref syntax errors in connector docs

["featzhang (Jira)" <ji...@apache.org>]

featzhang created FLINK-39045:
---------------------------------

             Summary: [docs] Add automatic fix for Hugo ref syntax errors in connector docs
                 Key: FLINK-39045
                 URL: https://issues.apache.org/jira/browse/FLINK-39045
             Project: Flink
          Issue Type: Improvement
          Components: Documentation
            Reporter: featzhang


h2. Description

The Hugo documentation build fails with {{REF_NOT_FOUND}} errors when building connector documentation that references main Flink documentation pages with anchors.
h2. Error Message

 

{{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. Root Cause

Some external connector repositories (e.g., flink-connector-aws) use incorrect Hugo ref shortcode syntax when referencing main Flink docs with anchors:
 * *Incorrect:* {{{\{< ref "docs/ops/production_ready/#set-uuids-for-all-operators" >}}}}
 * *Correct:* {{{\{< ref "docs/ops/production_ready" >}}#set-uuids-for-all-operators}}

Hugo's {{ref}} shortcode does not support anchors inside the path parameter. Anchors must be placed outside the shortcode.
h2. Proposed Solution

Add an automatic detection and fix mechanism in {{docs/setup_docs.sh}} to correct these syntax errors after integrating external connector documentation. This ensures documentation builds successfully regardless of syntax errors in connector repositories.
h2. Impact
 * Documentation builds fail in CI/CD pipelines
 * Prevents proper documentation deployment
 * Affects all versions that integrate external connector docs

h2. Labels
 * Type: Bug
 * Component: Documentation
 * Priority: Major



--
This message was sent by Atlassian Jira
(v8.20.10#820010)