[Pitch] Adding alignment control to the `@Column` directive

Development Swift-DocC
,
1

I would like to propose adding an optional alignment parameter to the @Column directive to provide more flexible content layout control within grid-based documentation layouts. This would allow documentation authors to horizontally align column content at the leading, center, or trailing position of the column's flex container.

Motivation

The @Column directive currently supports only the size parameter, which controls how many columns a column spans. While this handles the grid structure well, there is no way to control horizontal alignment of content within a column. This is particularly useful when you want to align content consistently—for example, centering a table or aligning text to the right.

Proposed Solution

Add an optional alignment parameter to @Column that accepts one of three values:

  • leading (default): aligns content to the left of the column
  • center: centers content horizontally within the column
  • trailing: aligns content to the right of the column

The implementation would render the column as a display: flex; flex-direction: column container with the corresponding align-items CSS value.

Syntax

@Column(alignment: center) {
    This is a centered paragraph!
}

@Column {
    This content aligns to the left by default.
}

Thoughts and feedback welcome!

6 Likes
2

+1 from me.

I might suggest using start, center, end names to more directly align with the terminology used for CSS logical values and flexbox axes and avoid explicit directional terms like "left" and "right" when describing these in case DocC ever supports rtl language content in the future.

1 Like
3

This is a good addition to the @Column directive's functionality. +1

The start and end terminology is an interesting perspective but I feel that there are several advantages to the leading and trailing terminology. Primarily that it (leading and trailing) is the terminology that DocC already uses, both in the section about aligning table columns in the user-facing documentation and for other features in the "Render Node" specification.

Even without the precedent for the "leading" and "trailing" terminology in DocC, I believe that the majority of the target audience will be more familiar with that terminology, over the CSS terminology, due to the long history of "leading" and "trailing" being used for similar layout concepts in Swift and Objective-C API. To name a few:

2 Likes
4

Thanks for the feedback, everyone! I'm ready to move forward with implementation. Before I dive in, I want to make sure I'm on the right track:

Should this be gated behind an experimental feature flag in swift-docc, or is the optional parameter sufficient since it defaults to the current behavior?

Any other guidance would be helpful.

1 Like
5

I personally feel that this doesn't need to be gated behind an experimental feature flag.

The primary reason to use an experimental feature flag is to reserve the right to make breaking changes so that one can make refinements based on people's feedback when they're able to try out the new feature more widely. However, in this case I feel that it's very unlikely that there would be any feedback from developers—that could only be discovered from using the alignment control in a real project—that would require changes to either the syntax or the way the alignment information is represented in the JSON output files. This enhancement is also is entirely additive and backwards compatible, so there's no documentation markup that would break from these changes (and therefore require a feature flag to opt-in to a new behavior).

1 Like