-
Notifications
You must be signed in to change notification settings - Fork 221
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
Tracking issue to upgrade to the latest Hugo when markdown rendering issues have been addressed #1091
Comments
I had assigned myself #2380 and was looking into what was going on. Which led to me this issue. I ended up trying the latest version of Hugo, which is using blackfriday 1.5.3. The nested code we're generating now certainly seems better with Hugo 0.65.3 vs. the pinned version from what I can tell. vs. Are there other pages we've seen in the past that suffered from this issue? It'd be nice to check them and if they seem fine, let's update so that our tutorials look better? I did notice that |
The issues were mostly in tutorial content, where we have lists and code fences within lists. When we ported the docs from Jekyll to Hugo, we had some tutorial content that I had to manually tweak to workaround similar rendering issues as in the screenshot above. This involved tweaking the content to not use code fences. One way I worked around it was by removing the code fence and just indenting the content, which does make it render as a code block (albeit, without a specified language for syntax highlighting). In more recent cases, I realized the In any case, these workarounds worked as of Hugo v0.55.4, but later versions of Hugo adopted newer versions of Blackfriday, which contained new bugs (linked to in the description of this issue above) which caused rendering regressions. And since then, we're now generating tutorial content from our examples repo, and the markdown from those example READMEs does not have any workarounds in place, hence the poor rendering for #2380. But it's been many months since I've tried more recent versions of Hugo. If the latest version fixes these issues, we should definitely move to it! We've also had to deal with other Blackfriday quirks. It doesn't render markdown within HTML blocks, so we've had to workaround this by wrapping markdown content inside HTML blocks with a I mentioned on Slack the other day that Hugo, as of v0.60.0, is now using Goldmark rather than Blackfriday as the default markdown renderer: https://gohugo.io/news/0.60.0-relnotes/ Goldmark is CommonMark compliant, so if we moved to that, we should be able to also move away from the It'd be interesting to try building the site with the latest version of Hugo with Goldmark enabled, to see how it fares. We'd have to go through the Config to make sure we're not losing anything significant switching to Goldmark. It'd be worth building the site with v0.55.4, and then with the latest version with Goldmark (or still with Blackfriday, if that makes it easier as a first step to moving to the latest version of Hugo), and then diff the generated HTML to see what the changes look like. |
Note: If we do end up moving forward with a Hugo upgrade, in addition to pinning to the more recent version in this repo, we'll also need to update the version that Pulumify uses here: https://github.com/pulumi/actions-pulumify/blob/43f558cc4749b6444102d578d72f03981dedc6ed/Dockerfile#L19-L21 |
I brought this into M33 to investigate if upgrading Hugo was our only option to workaround an OOM issue we were hitting on Travis with new resource docs. So I did a quick POC of upgrading to 0.63.0 and things looked good mostly. There were a few issues, but moving this to M34 so that we can focus on this while not in the midst of rolling out the resource docs. |
@chrsmith the throwaway repo that was setup to facilitate viewing diffs between files generated with 0.55.4 and some other (newer) version of Hugo is https://github.com/pulumi/hugo-upgrade-throwaway. |
Cannot close issue without required labels: |
Recent versions of Hugo have bugs in the markdown renderer (Blackfriday) that prevents fenced code from rendering correctly in lists when a language is specified. Many of our tutorials are made up of ordered lists of steps, each step containing a code snippet.
Until these issues are addressed, we've pinned to Hugo v0.55.4, which is the latest release that does not contain the regression.
We should ensure these issues are addressed and adopted by Hugo so we can stay current with the latest versions of Hugo.
The text was updated successfully, but these errors were encountered: