Repository navigation
fix: add j2_line_comment_prefix back to mkdocs configuration - #4822
Conversation
Signed-off-by: Joey Chen <142381267+JoeyC-Dev@users.noreply.github.com>
|
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 Tip We noticed you've done this a few times! Consider joining the org to skip this step and gain Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions 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. |
j2_line_comment_prefix back to mkdocs configuration
RoseWrightdev
left a comment
There was a problem hiding this comment.
I think a simple revert is the best path forward. A comment noting the warning could help prevent my mistake in the future.
|
/ok-to-test thanks |
|
[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 DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
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. |
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.
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?:
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:
However,
j2_line_comment_prefixis being used since 2022 and cause no problem: 9d9a10fAfter 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:
j2_comment_start_stringandj2_comment_end_stringinstead, as they are being listed as plugin's recognized parameters: https://github.com/fralau/mkdocs-macros-plugin/blob/0536f4da1dc643e1fa1f0cc90e71512ada67dc04/mkdocs_macros/plugin.py#L145-L146j2_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_stringandj2_comment_end_string, then I can update the config accordingly in this PR.For now, issue fixed as shown:

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