Enhancement: Improve formatting for commands containing asterisks using CSS roles

[rolfedh]

Problem Description

The current SSG topic, Commands in code blocks, prescribes using asterisks to format commands as bold text.

Enclosing commands that already contain an asterisk in a pair of asterisks creates parsing conflicts that "break" the command. For example:

$ *for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); do oc delete pods --all -n $I; done*

The first asterisk in the command (items[*]) terminates the bold formatting prematurely, causing the rest of the command to render incorrectly and exposing the trailing asterisk.

Screenshot of source:

Screenshot of output showing how the asterisk in .items[*] terminates the bold formatting, makes that asterisk disappear, and exposes the asterisk at the end of the command.

Potential Workarounds and Their Limitations

1. Escaping asterisks

*$ for I in $(oc get ns -o jsonpath='{range .items[\\*]} ...')*

Issues:

• Requires manual escaping of every asterisk in the command
• Error-prone and difficult to maintain
• Reduces readability of source documentation

2. Attribute substitution

:asterisk: *
$ *for I in $(oc get ns -o jsonpath='{range .items[{asterisk}]} ...')*

Issues:

• Adds complexity with attribute definitions
• Makes source less intuitive to read and edit
• Requires consistent attribute management across documents

Possible Solution

To avoid parsing conflicts and achieve the desired bold formatting, a possible solution might be to specify a role in the source, role=command, and combine that with CCS.

[source,terminal,role=command]
----
$ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \
    do oc delete pods --all -n $I; \
    sleep 1; \
    done
----

Then apply styling via CSS:

.command {
    font-weight: bold;
    background: #f5f5f5;
    border-left: 4px solid #0072c6;
    padding: 0.5em;
}

Benefits of This Approach

1. No parsing conflicts: Literal asterisks in commands are preserved without escaping
2. Flexible styling: CSS provides more formatting control than inline markup
3. Semantic clarity: Explicitly identifies content as commands vs. output
4. Migration compatibility: Role-based formatting aligns better with structured authoring principles (separating content from presentation) and DITA migration paths
5. Maintainability: Centralized styling through CSS reduces maintenance overhead

[rolfedh]

Here is a sampling of commands among the openshift-docs/modules that would be affected by this issue.

openshift-docs_modules_with_commands_that_contain_an_asterisk.txt

[rolfedh]

@bergerhoffer's question in Slack suggests an even more straightforward solution, which I'll paraphrase: with command blocks, do we still need to bold commands to distinguish them from output?

[rolfedh]

Anyone, please feel free to take up this issue and work on a solution in consultation with stakeholders.

[IngridT1]

@rolfedh Are you just suggesting that we should remove the requirement for commands to be in bold?