Support for Adding Top-Level Comments in Generated YAML

[NayanTheSpaceGuy]

Problem

Currently, the tool allows adding comments inside fields, but it does not support adding comments outside of fields—such as at the beginning of the file (header comments) or between top-level key-value pairs.

This limitation makes it difficult to include important metadata like license notices, copyright information, file descriptions, or general documentation directly within the YAML output.

Proposed Feature

Enable users to define top-level comments, including:

• Header comments (before the first key-value pair)
• Standalone comments between top-level fields

Use Case

• Ensuring compliance by adding license and copyright notices.
• Providing documentation within YAML for better readability.

Would it be possible to support this feature? It would be incredibly useful!

[StefMa]

Hi,
I am not sure if I fully understand your request. Itsm is about having comments in the yaml file itself? Or about having a top level comment on top of the file? 🤔
The latter can be supported quite easily. Somewhat I do this already right?
The latter is a bit more complicated. See also apple/pkl#690

[StefMa]

This might also be related:
apple/pkl#376

[NayanTheSpaceGuy]

Hi,

To clarify, I am specifically referring to top-level comments at the very beginning of the YAML file itself. These would include comments such as license notices, copyright information, or general file descriptions.

Yes, you have already added the 'Do not modify...' comment, and it can be overridden by overriding the output {} section.
I am asking for the ability to add additional comments before that line. This is especially important for adding metadata like SPDX copyright and license identifiers.

Here’s a clear example of what I am asking for:

# SPDX-FileCopyrightText: Copyright line here
#
# SPDX-License-Identifier: License here

# Do not modify!
# This file was generated from a template using https://github.com/StefMa/pkl-gha

# YAML content starts here
...

Currently, this is not possible since the 'Do not modify...' comment is always the first and only top-level comment. It would be very useful to have the ability to add other comments before it.

Additionally, I’m also requesting the ability to include comments anywhere in the YAML file, not just at the top. For example:

# SPDX-FileCopyrightText: Copyright line here
#
# SPDX-License-Identifier: License here

# Do not modify!
# This file was generated from a template using https://github.com/StefMa/pkl-gha

...
# Use checkout v3 as xyz tool has currently issues with v4
jobs:
  checkActionsConverted:
    runs-on: ubuntu-latest
    steps:
    - name: checkout
      uses: actions/checkout@v3
...

This would allow users to add additional documentation and metadata throughout the YAML file as needed.

Would it be possible to implement support for at least adding a comment at the very beginning of the generated YAML file, before the 'Do not modify...' line? This is much needed. Additionally, if pkl language allows it, enabling comments throughout the entire generated YAML file would be very helpful.