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)
