-
Notifications
You must be signed in to change notification settings - Fork 14.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Remove the use of the capture shortcode (or: how to prepare for Goldmark) #20780
Comments
A side effect of the I'm OK with losing that. Instead, that kind of check is more of a job for a linter or similar automated process. Archetypes also sound like a helpful approach. We could still use a shortcode for the section titles? Eg ## {{< heading-whatsnext >}} Example future lints:
|
@sftim you would still be able to use all the shortcodes you want, it's just that very special There could be a possibility to change these capture blocks with "something else", e.g. separate them into different Markdown-files, e.g. |
Sounds good to me. |
@bep, Are you referring to: I don't fully understand what
|
@kbhawkey not sure what you mean by So, if you had Markdown that looked linke this:
In "earlier days" the "Another title" above would not be part of the TableOfContents produces unless you did some trickery.
That would be something that I would help out with and would be a one time hack that would make this task practical (it would be a gigantic job if done manually) and, if done correctly, guaranteed to produce the same output as you have today. In short it will inline all the Markdown, but keep the shortcodes as-is. |
So, use code from Hugo to generate what we think the files should have looked like in the first place (in an ideal world). Does that summarize that part of your proposal @bep? |
@sftim I guess so, but it depends a little on how much you like the current |
I admit that I don't fully understand the details of the proposal (need to think on this a bit more).
Without knowing more details, I typically favor non-custom solutions. |
As mentioned above, we could remove the requirement of capture statements and instead provide templates for some of the page-specific H2 level headings.
|
Combining a few ideas, the linter could check for: ## {{< heading-whatsnext >}} rather than ## What's next and this helps with localization. |
I would recommend you do:
The |
I also like the idea of using render hooks to catch problems. I don't know if it's a good idea / there's a better way. |
Archetypes could help with new content creation.
@bep, Any thoughts? |
I've seen a few issues (see #20942) that look hard to solve without either a significant rewrite or removal of the problematic capture shortcode. |
@kbhawkey as to validating the structure without
There are some ongoing work creating a render hook for headings in Hugo, see gohugoio/hugo#7133 (comment) -- I have had a little problem seeing "if it's worth it", but I can certainly see a value here. It would be an easy way to validate content structure while building. I have been a little busy with other work lately, but I'll cc @zacharysarah on this issue; I still think my initial post sums it up fairly good. |
I'm finding that the parser will not add an H2 heading from a shortcode Here is an example shortcode that gets called as:
Instead, this works (when the shortcode just returns a string): I'd rather have the entire statement wrapped in the shortcode so that authors can omit the |
PR #21359 is working towards fixing this |
Fixed in #21359 |
@sftim: Closing this issue. In response to this:
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. |
@zacharysarah asked me to do some investigative work figuring out if it would be possible/how hard to get this site up and running with Goldmark/latest Hugo (i.e. CommonMark compliant).
A lot of work on this has already been done in #19907.
I diffed a sub-set (English content, no blog) using stripped down templates to make it easier to see some patterns. A very common pattern was HTML blocks treated as Markdown, so I created this yuin/goldmark#125 -- which is closed (I agree about that).
So, to use HTML blocks in Markdown and still be CommonMark compliant, we would either have to:
{{< wrap >}}
shortcode or something, so Goldmark never sees it.Both of the above could probably be easily scripted (esp. the last part), had it now been for the indirection of the
{{% capture %}}
shortcode, which produces Markdown with template includes etc.Of the 365 different files (out of 667 samples), 226 of them use the
{{% capture %}}
shortcode.A simple example:
{{% capture prerequisites %}} ## Hello {{< version-check >}} {{% /capture %}}
The inner
{{< version-check >}}
uses{{<
which marks it as (usually) raw HTML. But since it's included in a{{%
block, its content will be passed to Goldmark.A long story short, to solve this issue I think we either need to
capture
shortcode so we can get better control on this from the Markdown file itself.The
{{% capture %}}
templating was ported by me from the old Jekyll site. I suspect its biggest value is that it sets a common structure for disposition of guides and avoids some repetition. But:{{%
brackets, they will be part of the ToC).I think it should be possible to temporarily patch Hugo to make it do a very shallow render that expands this
capture
one level and writes the files to disk. It would be a big change set, but it would be a correct one.The text was updated successfully, but these errors were encountered: