[wip] replace capture stmts #21277

kbhawkey · 2020-05-28T21:11:12Z

Testing replacement of capture statements.

k8s-ci-robot · 2020-05-28T21:11:58Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign kbhawkey
You can assign the PR to them by writing /assign @kbhawkey in a comment when ready.

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

Needs approval from an approver in each of these files:

OWNERS

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

kbhawkey · 2020-05-28T21:13:34Z

Related to #20977, #21253.

netlify · 2020-05-28T21:23:20Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 69f246d

https://deploy-preview-21277--kubernetes-io-master-staging.netlify.app

sftim · 2020-05-28T21:32:10Z

Based on #20780 (comment) I'm convinced that this approach, or something very close to it, is the right way to go.

zacharysarah

@kbhawkey Looks solid. 👍

I left some notes about work to follow after this PR, specifically about updating page templates and the style guide.

zacharysarah · 2020-05-28T21:45:51Z

i18n/en.toml

+[options_heading]
+other = "Options"
+
 [prerequisites_heading]
 other = "Before you begin"

+[seealso_heading]
+other = "See Also"
+
 [subscribe_button]
 other = "Subscribe"

+[synopsis_heading]
+other = "Synopsis"
+


Thanks for adding these for localization! ✨

zacharysarah · 2020-05-28T21:50:59Z

config.toml

+  [markup.goldmark.parser]
+      attribute = true
+      autoHeadingID = true
+      autoHeadingIDType = "blackfriday"


For future reviewers: this attribute setting is a smart choice in the landscape of Hugo 0.62.2.

gohugoio/hugo#6616

zacharysarah · 2020-05-28T21:53:45Z

content/en/docs/concepts/_index.md

@@ -1,17 +1,17 @@
 ---
 title: Concepts
 main_menu: true
-content_template: templates/concept
+# content_template: templates/concept


I'm ambivalent about whether to keep these lines or remove them, but it's not a blocker for this PR.

I think it's worth reviewing and possibly iterating later, but this seems like a reasonably conservative approach for now. If they prove to be crufty after 90+ days, it should be trivial to remove them later.

EDIT: If we update the templates themselves, we may be able to restore the attribute declaration without harm.

I agree. I was hesitant to remove entirely, but not against removing.

Some more thoughts on this. I don't want to leave a variable commented out in the front matter. I think it makes sense to either:

Remove the content_template variable if the templates files are no longer needed.

Change the content_template variable/value to: content: concept, content: task, content: tutorial. Leave some information about the page type so that there is flexibility in the future.

content: concept (etc)

I like the idea of this: it makes it easier to add a future lint for (for example) task-style content in the concepts section.

@kbhawkey if I wanted to add some JSON-LD metadata to declare, in the rendered page, “this page describes a concept” what approach would you recommend? A render hook?

I'm thinking of starting out with a no-op render hook that checks for a valid value of either content_template or content and doesn't otherwise change the pages. However, I've never tried using Hugo render hooks.

@sftim, Seems interesting. Do you need a render hook? The metadata appears in the header?

Thinking,
content_type: tasks vs. content_type:task?
The directory structure uses the plural and the card dict in the front matter uses the plural for name.

card: name: tasks weight: 10

zacharysarah · 2020-05-28T21:57:38Z

content/en/docs/concepts/_index.md

 weight: 40
 ---

-{{% capture overview %}}
+<!-- overview -->


I like this strategy for replacement. 👍

We do need to update page templates and the contribution docs accordingly.

I moved contribute/style/page-templates to contribute/style/page-styles and cleaned up the template content.
There are many links to the page-templates page throughout the contribute section -- wow.
I did not deliberate on renaming the new page. Surely, the name and content can be changed.

Preview:
https://deploy-preview-21277--kubernetes-io-master-staging.netlify.app/docs/contribute/style/page-styles/

Ideas to move forward:
With these changes, the site will be using (temporarily) two ways to render the pages.
One idea is to create single commits for migrating each localization or leave these changes as en only. I expect it would be easier to remove the templates and related code after the capture statements are removed.
Should decide whether to remove the content_template front matter or update as suggested.

single commits for migrating each localization

👍 to that approach

kbhawkey · 2020-05-28T22:55:15Z

Added a separate commit with the updated fr pages. Testing on a localization.

k8s-ci-robot · 2020-05-30T18:29:34Z

@kbhawkey: PR needs rebase.

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/test-infra repository.

kbhawkey · 2020-06-01T14:26:23Z

Moved work to PR #21359.

kbhawkey · 2020-06-03T20:45:42Z

/close

k8s-ci-robot · 2020-06-03T20:45:55Z

@kbhawkey: Closed this PR.

In response to this:

/close

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/test-infra repository.

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels May 28, 2020

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels May 28, 2020

k8s-ci-robot requested review from aanm and aaron-prindle May 28, 2020 21:12

zacharysarah approved these changes May 28, 2020

View reviewed changes

kbhawkey force-pushed the kb-caputre-stmts-fixup2 branch from 38149e2 to ce473b9 Compare May 28, 2020 22:51

k8s-ci-robot added the language/fr Issues or PRs related to French language label May 28, 2020

kbhawkey added 4 commits May 29, 2020 09:31

config for removing capture stmts

52bb47b

generate en content without capture

c1ca59f

fr capture replacement, testing

57efd89

replace capture template references

69f246d

kbhawkey force-pushed the kb-caputre-stmts-fixup2 branch from ce473b9 to 69f246d Compare May 29, 2020 14:57

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label May 30, 2020

kbhawkey mentioned this pull request May 30, 2020

removing capture statements #21359

Merged

k8s-ci-robot closed this Jun 3, 2020

kbhawkey deleted the kb-caputre-stmts-fixup2 branch July 30, 2020 11:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[wip] replace capture stmts #21277

[wip] replace capture stmts #21277

kbhawkey commented May 28, 2020

k8s-ci-robot commented May 28, 2020

kbhawkey commented May 28, 2020

netlify bot commented May 28, 2020 •

edited

sftim commented May 28, 2020

zacharysarah left a comment

zacharysarah May 28, 2020

zacharysarah May 28, 2020

zacharysarah May 28, 2020 •

edited

kbhawkey May 28, 2020 •

edited

kbhawkey May 30, 2020

sftim May 30, 2020

sftim May 30, 2020

kbhawkey May 30, 2020

kbhawkey May 30, 2020

zacharysarah May 28, 2020

kbhawkey May 28, 2020

kbhawkey May 29, 2020

kbhawkey May 30, 2020

sftim May 30, 2020

kbhawkey commented May 28, 2020

k8s-ci-robot commented May 30, 2020

kbhawkey commented Jun 1, 2020

kbhawkey commented Jun 3, 2020

k8s-ci-robot commented Jun 3, 2020

[wip] replace capture stmts #21277

[wip] replace capture stmts #21277

Conversation

kbhawkey commented May 28, 2020

k8s-ci-robot commented May 28, 2020

kbhawkey commented May 28, 2020

netlify bot commented May 28, 2020 • edited

sftim commented May 28, 2020

zacharysarah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zacharysarah May 28, 2020 • edited

Choose a reason for hiding this comment

kbhawkey May 28, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented May 28, 2020

k8s-ci-robot commented May 30, 2020

kbhawkey commented Jun 1, 2020

kbhawkey commented Jun 3, 2020

k8s-ci-robot commented Jun 3, 2020

netlify bot commented May 28, 2020 •

edited

zacharysarah May 28, 2020 •

edited

kbhawkey May 28, 2020 •

edited