Skip to content

fix: add j2_line_comment_prefix back to mkdocs configuration - #4822

Merged
k8s-ci-robot merged 1 commit into
kubernetes-sigs:mainfrom
JoeyC-Dev:hideYamlRef
May 4, 2026
Merged

k8s-ci-robot merged 1 commit into
kubernetes-sigs:mainfrom
JoeyC-Dev:hideYamlRef

Conversation

@JoeyC-Dev

@JoeyC-Dev JoeyC-Dev commented May 3, 2026 •

Copy link
Copy Markdown
Contributor

What type of PR is this?

/kind bug
/kind regression

What this PR does / why we need it:
The PR #3999 (review) caused a site regression that prevents reference headers in YAML files from being hidden.

image

Src: https://deploy-preview-3999--kubernetes-sigs-gateway-api.netlify.app/api-types/httproute/

Which issue(s) this PR fixes:

None

Does this PR introduce a user-facing change?:

NONE

Root Cause Analysis (RCA):

Since this issue has already been causing problems on live pages since April 30, I’m putting it here instead of continuing the solution discussion in Slack.

This issue was caused by a false positive warning that misled the developer into removing this line:

WARNING -  Config value 'plugins': Plugin 'macros' option 'j2_line_comment_prefix': Unrecognised configuration name: j2_line_comment_prefix

However, j2_line_comment_prefix is being used since 2022 and cause no problem: 9d9a10f

After further digging into the issue, I found that this warning should be categorized as an upstream issue. Details here: fralau/mkdocs-macros-plugin#288

Solution:
So, two solutions:

  1. Use j2_comment_start_string and j2_comment_end_string instead, as they are being listed as plugin's recognized parameters: https://github.com/fralau/mkdocs-macros-plugin/blob/0536f4da1dc643e1fa1f0cc90e71512ada67dc04/mkdocs_macros/plugin.py#L145-L146
  2. Since this should be intended behaviour as upstream project document says, submit issue to upstream to fix (fix is merged in upstream, pending on version release), and we continue using j2_line_comment_prefix. (simple revert)

Solution 1 is to simply avoid emitting the warning. Solution 2 is to keep the original approach, which has been in place for four years.

I put solution 2 here. When upstream releases a new version with the fix, @dependabot should be able to update the dependency automatically (so the relative warning will no longer be emitted). If SIG Gateway API decides to use j2_comment_start_string and j2_comment_end_string, then I can update the config accordingly in this PR.

For now, issue fixed as shown:
image
Src: https://deploy-preview-4822--kubernetes-sigs-gateway-api.netlify.app/api-types/httproute/

Signed-off-by: Joey Chen <142381267+JoeyC-Dev@users.noreply.github.com>
@k8s-ci-robot k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/bug Categorizes issue or PR as related to a bug. kind/regression Categorizes issue or PR as related to a regression from a prior release. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels May 3, 2026
@k8s-ci-robot
k8s-ci-robot requested review from rikatz and youngnick May 3, 2026 13:17
@k8s-ci-robot k8s-ci-robot added size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels May 3, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

Hi @JoeyC-Dev. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@JoeyC-Dev JoeyC-Dev changed the title fix: add j2_line_comment_prefix back to mkdocs configuration fix: add j2_line_comment_prefix back to mkdocs configuration May 3, 2026

@RoseWrightdev RoseWrightdev left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a simple revert is the best path forward. A comment noting the warning could help prevent my mistake in the future.

@rikatz

rikatz commented May 4, 2026

Copy link
Copy Markdown
Member

/ok-to-test
/lgtm
/approve

thanks

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels May 4, 2026
@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 4, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: JoeyC-Dev, rikatz

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 4, 2026
@k8s-ci-robot
k8s-ci-robot merged commit 9d55cca into kubernetes-sigs:main May 4, 2026
188 checks passed
@JoeyC-Dev
JoeyC-Dev deleted the hideYamlRef branch May 4, 2026 01:28
@JoeyC-Dev

Copy link
Copy Markdown
Contributor Author

I think a simple revert is the best path forward. A comment noting the warning could help prevent my mistake in the future.

Since the upstream project has already merged the fix, let’s wait for a while. If a new version is released, we update the dependency instead after then (or probably @dependabot will do it), so there are no more warnings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/bug Categorizes issue or PR as related to a bug. kind/regression Categorizes issue or PR as related to a regression from a prior release. lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note-none Denotes a PR that doesn't merit a release note. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants