Snippets - omit specified lines

[hazzuk]

Proposal

Snippets feature. Remove lines inside a snippet that contain a remove/omit/hide notation (e.g. !-8<- ).

Motivation

Currently there are a couple of ways to control the contents of a snippet.

• Snippet Sections are great if you can group content together
• Snippet Lines are useful if the content layout isn't expected to shift

The use-case I have for snippets isn't really covered by these existing features. But would be solved if I could essentially "comment out" specific lines, adding a notation which would hide different lines.

Context

I have multiple source files which I'd like to include in my documentation, this is one example:

# SPDX-FileCopyrightText: 2026 hazzuk
#
# SPDX-License-Identifier: AGPL-3.0-only

---

hazzuk_core_traefik_enabled: false

hazzuk_core_traefik_stack_defaults:
  traefik:
    image: docker.io/traefik
    version: v3.6.15
    log_level: debug
    acme:
      staging_enabled: true
      email: cert@example.com
      staging_ca_server_url: "https://acme-staging-v02.api.letsencrypt.org/directory"
      live_ca_server_url: "https://acme-v02.api.letsencrypt.org/directory"
      zone_api_token: ""
      dns_api_token: ""
    dashboard:
      enabled: true
      forward_auth_enabled: true
      domain: "traefik.{{ karo_compose_root_domain }}"
    custom_domains_raw: |
      # - main: "*.int.{{ karo_compose_root_domain }}"
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth
    version: v5.0.7-distroless
    domain: "tinyauth.{{ karo_compose_root_domain }}"
    log_level: info
    oidc:
      client_id: ""
      client_secret: ""
  cetusguard:
    image: docker.io/hectorm/cetusguard
    version: v1.1.3
    log_level: 7

Users reading the documentation will essentially need to create a copy of this data structure. But the version I present to users needs to be stripped down significantly.

The problem I face is that the lines I need to omit from this file are so scattered, neither snippet lines or sections really works.

> snippet lines, very brittle
--8<-- "src.yml:10:10,13:13,14:16,19:23,27:27,31:35,38:38"

> snippet sections, arbitrarily excessive
--8<--
src.yml:part1
src.yml:part2
src.yml:part3
src.yml:part4
src.yml:part5
src.yml:part6
src.yml:part7
--8<--

---

Instead, being able to omit specific lines inside the source file itself would be hugely beneficial.

# SPDX-FileCopyrightText: 2026 hazzuk
#
# SPDX-License-Identifier: AGPL-3.0-only

---

hazzuk_core_traefik_enabled: false

hazzuk_core_traefik_stack_defaults:
  traefik:
    image: docker.io/traefik # !-8<-
    version: v3.6.15 # !-8<-
    log_level: debug
    acme:
      staging_enabled: true
      email: cert@example.com
      staging_ca_server_url: "https://acme-staging-v02.api.letsencrypt.org/directory" # !-8<-
      live_ca_server_url: "https://acme-v02.api.letsencrypt.org/directory" # !-8<-
      zone_api_token: ""
      dns_api_token: ""
    dashboard:
      enabled: true
      forward_auth_enabled: true
      domain: "traefik.{{ karo_compose_root_domain }}" # !-8<-
    custom_domains_raw: |
      # - main: "*.int.{{ karo_compose_root_domain }}"
  tinyauth:
    image: ghcr.io/steveiliop56/tinyauth # !-8<-
    version: v5.0.7-distroless # !-8<-
    domain: "tinyauth.{{ karo_compose_root_domain }}" # !-8<-
    log_level: info
    oidc:
      client_id: ""
      client_secret: ""
  cetusguard:
    image: docker.io/hectorm/cetusguard # !-8<-
    version: v1.1.3 # !-8<-
    log_level: 7

--8<-- "src.yml:10"

This removes the huge burden of ensuring the docs stay up to date with the source files. As snippets are simply configured inside the source file itself.

Additional note

Being able to declare blocks as well would be useful. As sometimes a comment can't be added to the end of a line.

    # !-8<- [start]
    custom_domains_raw: |
      # - main: "*.int.{{ karo_compose_root_domain }}"
    # !-8<- [end]