Shortcodes in Cloudify documentation are not rendered properly

Description

During review of the UI documentation () I found many pages not rendered properly - tips, notices, warnings and possibly other templates (in Hugo named shortcodes) are not displayed the way they should be (and the way they was few months ago).

Examples:
1.

2.

3.

List of pages affected (these are I found, possibly there are more):

  1. Installing and Configuring a Cloudify Manager

  2. Packaging a Blueprint

  3. Configuring Multi-Tenancy

  4. Resource Visibility

  5. Maintenance Mode

  6. Managing Users

  7. Okta Authentication

  8. Built-in Workflows

  9. Creating Custom Workflows

  10. Advanced Blueprint Example

  11. Debugging Cloudify Workers

I found that this PR intended to fix some of the problems, but I think the solution introduced there is not the right one. The reason for the problem is that in June (see this PR) we moved from Hugo v0.42 to Hugo v0.72. In between (Hugo v 0.55) there was backward incompatible change, for details see: Hugo v0.55 release notes or Hugo Documentation - shortcodes .

We are using docDock hugo theme. It's not maintained properly, but that's probably another issue to be solved. Important thing is that it was forked from Matcornic Learn theme which potentially has fix for the problems with shortcodes already applied.

Probably we can use the same approach as in original theme - see this commit - just add:

at the beginning of each shortcode affected.

Steps to Reproduce

See description.

Why Propose Close?

None

Activity

Show:
Jakub Niezgoda
September 10, 2020, 10:26 AM

I spent today morning on digging into that issue I encountered during UI documentation review. I have potential solution. I’ll assign it to me and try to solve before I move with the updates I plan.

Ofer Yarom
September 10, 2020, 10:31 AM

Try adding the following tag to these pages: {{%children style="h3" description="true"%}}

Jakub Niezgoda
September 10, 2020, 10:41 AM

As I wrote at the end of the description I think that is not the right solution as you have to put it before first use of affected shortcodes. In case of pages with subpages this shortcode will display the list of the subpages. I found some cases I don’t want to list it at the top, sometimes you want to present a description and then - at the bottom - show the subpages list.

The better solution IMHO is the one I suggested in the last paragraph of the description. The long-term solution would probably involve also migrating to a new theme which is maintained and provide more shortcodes out-of-the-box without necessity to maintain it on our side.

Ofer Yarom
September 10, 2020, 10:42 AM

Fixed

Assignee

Jakub Niezgoda

Reporter

Jakub Niezgoda

Labels

Severity

High

Target Version

5.1

Premium Only

no

Found In Version

5.1

QA Owner

None

Bug Type

regression bug

Customer Encountered

No

Customer Name

None

Release Notes

yes

Priority

None

Epic Link

Sprint

None

Priority

Unprioritized
Configure