Section/blocks improvments

[theoephraim]

It is often useful to group multiple items in a .env file together somehow. Currently with @env-spec, while we can add a comment block before a group of items, there is no additional semantic link between those items and the comment block, or any way to end a section. We would like to introduce some mechanism for creating an explicit "section" within a file that multiple items can then be a part of, and ideally be able to nest sections to provide further hierarchy.

This notion of items being part of a section allows a few new things:

• root decorators from a section can be applied to all children of the section, rather than only having them apply to an entire file
• autogenerated docs or any other visualizations of config can then use these sections for visual display / organization
• IDE extensions could add collapse/sticky headers based on this hierarchy

Proposal

Introduce into the language a new concept of a "heading" which will begin a "section". Taking the familiar syntax from markdown, a heading begins with multiple # symbols, for example ## This is a heading. Like markdown, using additional # characters allows us to have a notion of depth/levels, which can then be used to create hierarchy.

## Section 1
ITEM1=
ITEM2=

### Section 1.1
ITEM3=

### Section 1.2
ITEM4=

## Section 2
ITEM5=

Further details:

• A single # is always just treated as a regular comment. Using 2 or more leading # characters before a space and some text would be treated as a "heading"
• Commented out comments may be useful when toggling items on/off. In this case a preceeding # will still work, and result in something like this

# # @required
# ITEM1=

• Note that currently 3 or more ### characters is considered a divider. We may want to completely discontinue the use of # as a divider character, set some upper threshold (for example 5), or require an additional space after the first # to consider it as a divider

# just a comment
## Heading (1)
### Heading (2)
################ over some threshold we likely consider it a divider again (or just a regular comment)
# ### the extra space could let us consider this as a divider

• A heading is not attached to the items/comments below it, unless it is part of a comment block that ends with a divider. Otherwise it exists on its own.

## Section A
# comment about ITEM1 - NOT attached to the heading above
ITEM1=
ITEM2=

## Section B
# notes about this section
# @decorators # root decorators that apply to the items within this section
# (the closing divider here makes these lines into a comment block)
# ---
# Item 3 description
ITEM3=

• A section is begun only by a heading
• Sections will be nested if the heading level/number is greater than the previous one
• A section will be ended by another section of the same (or lower) level, by a divider, or by a comment block without a header that ends with a divider
• If a header is the start of a comment block that ends with a divider, that divider does not end the section, it is instead just part of the start, but a freestanding divider (or comment block that ends with a divider) will also end a section

## Section 1
# item 1 comment
ITEM1=
### Section 1.1
ITEM2=
# freestanding comments are ok, as long as this block doesn't end with a divider

ITEM3=
# ------ divider ends current section (1.1)

ITEM4= # still in section 1

## Section 2 # <- ends section 1
ITEM5=

• When looking for root decorators tied to an item, we would follow up the chain of section parents to the document header

• EDGE CASE, if a file begins with a section header, we would not automatically apply the root decorators to everything in the file. Which means that no global level decorators (like disabling security measures) could be used.

# implicit document root
# @decorator # < applied to the whole file
# ---

versus

## Section
# @decorator # < now only applied to children of this section
# ---

## another section
# ...

[trevordcampbell]

I like this idea of sectioning. I've ben mulling over this for a couple of days.

I admire the idea to utilize markdown-style section definition and nesting with "#" declarations, but my concern is that the proposed syntax might be too easily confused with comments and also prone to user error (could be easy to miss what should be a comment vs a first-level section, and users may accidentally comment out blocks of code during development which may then impact sections and section nesting. This feels like a semi-fragile approach toward sectioning.

I've been thinking of possible alternatives that could achieve the same results while still having good UX / DX, and preserving the desired section behaviors. I have two alternative options for consideration...

---

Option A: Decorator-Based Sections (@section)

Note

Leans into env-spec’s existing “metadata in comments” model while making sections explicit and visually distinct from normal comments.

Syntax Examples

# @section path="Services/Backend" title="Backend"

# @required @docsUrl=https://internal/wiki/backend
DB_URL=
DB_USER=

# ---

# @section path="Services/Backend/Auth" title="Auth"

# @sensitive
JWT_SECRET=

# ---

// In this example, using the `# ---` delimiter to end a section.

# @section path="Services/Backend" title="Backend"

# @required @docsUrl=https://internal/wiki/backend
DB_URL=
DB_USER=

# @endsection

# @section path="Services/Backend/Auth" title="Auth"

# @sensitive
JWT_SECRET=

# @endsection

// In this example, using an optional `# @sectionend` decorator to end a section

# @section path="Services/Backend" title="Backend"

# @required @docsUrl=https://internal/wiki/backend
DB_URL=
DB_USER=

# @section path="Services/Backend/Auth" title="Auth"

# @sensitive
JWT_SECRET=

# @endsection path="Services/Backend"

// In this example, using an optional `# @sectionend` decorator to end the top level-section.

Parsing & Semantics

Start:

A decorator comment line containing @section starts a section. (env-spec already distinguishes decorator lines from regular comments.)

Attributes:

Path:

• Slash-delimited hierarchical path. Guarantees unambiguous nesting independent of visual proximity.

• Optional id, title, icon, etc., for IDE / Docs.

Header block:

Any decorator/comment lines until a divider (# --- or # ===) are the section header; their decorators apply to all items in the section (and are inherited by descendants), matching how root header decorators work today.

End:

Implicit:

The section ends when another @section appears whose path is the same prefix length or shorter (i.e., a sibling or ancestor), or when EOF is reached.

Explicit (optional):

Allow # @endsection to close section early (useful when paths aren’t convenient). If present, it wins over implicit rules.

Nesting:

Derived from path. No reliance on ## depth counting.

Inheritance:

When resolving decorators for an item, walk up path components (Auth → Backend → Services → Document header). This mirrors the RFC’s approach of “follow parents to the document header.”

Back-compatibility:

Non-env-spec tools see these as harmless comments; no interaction with # count.

DX:

Easy to lint:

• @section must be followed by a divider within N lines; path must be unique; missing parent paths can warn.

• IDE folding / breadcrumbs are trivial: split path on /.

• Auto-fixers can convert ad-hoc comment headings into @section with a one-shot codemod.

Why This Fits Varlock Well:

This approach reuses env-spec’s decorator comment line vs regular comment distinction and divider semantics, avoiding new token classes while staying explicit.

---

Option B: INI / TOML-style headers ([section] / [a.b])

Syntax Eamples

[Services]
# @required
GLOBAL_TIMEOUT=30

[Services.Backend]
DB_URL=
DB_USER=

[Services.Backend.Auth]
JWT_SECRET=

# ---

Parsing & semantics

Start:

Any line of the form [\w+(\.\w+)*] opens a section; dotted names imply hierarchy. (Exactly how INI / TOML model table paths and subsections.)

End:

Implicitly closed by the next header of the same or ancestor path (mirrors INI’s “no explicit end; next header closes previous”).

Inheritance:

Walk the dotted path components.

Back-compatiblity:

Legacy dotenv loaders ignore these lines (not KEY=VAL), so they’re inert.

DX:

• Very legible; zero confusion with # comment declarations.

• Easy for IDEs to fold by bracket headers.

Trade-offs:

Introduces a non-comment line type to env files (a small conceptual step beyond pure dotenv).

Potential Variant:

Could also adopt TOML’s [[array.of.tables]] to model repeated groups (e.g., multiple OAuth providers).

---

Edge Cases & Rules of Thumb

Scattered items:

With Option A (paths) or B (dotted headers), you can group non-contiguous items by repeating the header later — no need to keep them physically contiguous (TOML tables behave like this).

Global decorators:

Keep the current “document header” semantics (comment block at top ending with a divider) for truly global knobs, and have section resolution climb: Item → nearest section → ancestor sections → document header.

Arrays of sections:

If you need multiple siblings with the same name (e.g., multiple provider entries), either:

• Option A: path="Auth/Provider:github", path="Auth/Provider:google" (label after :), or allow @section array="Auth/Provider" label="github".

• Option B: TOML-style [[Auth.Provider]] repeatable headers.

Off-by-one heading mistakes:

Both alternative syntax options eliminate “2 vs 1 hash” accidents.

---

Editor UX ideas

VS Code:

• Implement folding & breadcrumbs in the env-spec language extension using section nodes. One example of this is the Comment Anchors extension, which shows how section anchors drive sidebars in the editor / folding.

• Sidebar Docs generation via varlock extension: Render a left-hand nav using path / headers; surface inherited decorators in section summaries. Here's an example of what the Comment Anchors extension does here:
  

Lints/Auto-fixers:

• Warn if a header block (comments+decorators) lacks a terminating divider; offer to insert # --- / @sectionend / @sectionend path=<path>.

• Ensure variables under a section share a common name prefix (optional rule), helping readers recognize grouping even outside tooling.

---

Thoughts on these alternative syntax options?

[theoephraim]

First - thanks so much for taking some time to write out some ideas and discuss :)

Some initial thoughts:

• I don't love the idea of introducing anything thats not within a comment, as I don't think all legacy dotenv parsers will just ignore those lines. It's probably not actually important, but we've made it this far keeping everything pseudo .env compliant... That said, for option 2, I could imagine just doing something like # [Section]
• I had also considered @section/@endSection type decorators, but I worry they will get lost visually... Does it need to come first on the line? Does that line need a line break (or divider) before any item definition?
• While the explicit slash paths seems flexible, I'm not sure I like the idea of removing the link between the location in the file and the hierarchy, or allowing multiple instances of a section. Changes could also now require updating that path in many places and keeping it in sync. The one benefit I can imagine is being able to merge sections together from different files, although I'm not sure the complexity is worth it. Perhaps it could be an option, but the default is no paths necessary?
• I worry about anything that would allow easily interleaving sections in ways that dont really make sense

One very common pattern I'm thinking through from non-env-spec .env files is when a simple comment line is meant to be a section heading applied to multiple items, for example:

# ABC Config
ABC_ITEM1=
ABC_ITEM2=

# XYZ Config
XYZ_ITEM1=
XYZ_ITEM2=

Ideally one can easily mark those as section headers without adding (m)any additional lines - ie an explicit end section marker, or additional newline to break the header from comments attached to an item.

---

Decorator driven style

# @section="ABC Config" @sectionId="abc"
# this is a comment about the item
# @required
ABC_ITEM1=
ABC_ITEM2=

# @section(title="XYZ Config" id="xyz")  # < or could use a fn call?
XYZ_ITEM1=
XYZ_ITEM2=

• we need some way to break the section heading from the item comments, either a newline or a divider
• it is not visually distinct from the other comments/decorators
• we need some extra info to handle nesting, either a path or at least a "level" - which would not necessarily be visually distinct
• the title is now floating in the middle of the line, rather than at the beginning, like you would naturally want to do

---

Bracket/toml style

# [ABC Config] @sectionId='abc'
# this is a comment about the item
# @required
ABC_ITEM1=
ABC_ITEM2=

# [XYZ Config | id] # < more syntax options could be used here
XYZ_ITEM1=
XYZ_ITEM2=

The bracket style is a bit better and the additional leading # doesnt harm it too much

• we still need a way to handle nesting / level, and ideally its something visually obvious, rather than having to compare paths

---

Markdown heading style

## ABC Config # @sectionId=abc
# this is a comment about the item
ABC_ITEM1=
ABC_ITEM2=

## XYZ Config [xyz]
XYZ_ITEM1=
XYZ_ITEM2=

The markdown style is definitely simplest, as it just adds one character to convert it into a section heading rather than item description. I do think that the extra hash is visually distinct, and it feels somewhat familiar. The vscode extension would highlight it as well - bold, different color, so it would be very clear what is happening.

Many syntax options could be used to handle things like explicit id/icon/etc - although I think these would be rare, so focusing on simplicity of base case is most important

---

So in summary:

• not sure about the decorator driven style, I think this deserves some new syntax. I also think its important the title comes at the beginning of the line, as it feels natural and helps visually
• brackets or markdown style hashes I think can work, but want to make sure whatever it is feels familiar, and is visually distinct
• ideally whatever it is allows a user to convert a comment line into a heading with a simple change that doesnt force you to add multiple other lines
• should probably still keep it .env/bash compliant, meaning the heading line should be within a comment (start with #)

[trevordcampbell]

I am generally a fan of very visually distinct + verbose code — in my own .env files, I currently visually section them using something obscene like:

# ===========
# NETWORKING
# ===========

# --- SERVICE PORTS---
FRONTEND_PORT=3000
BACKEND_PORT=3001
POSTGRES_PORT=5433
REDIS_PORT=6379

# --- HOSTS --- 
DATABASE_HOST=localhost
REDIS_HOST=localhost

# =======================
# NEXT TOP-LEVEL SECTION
# =======================

...

As far as your response: The markdown-style approach is simple, yes, but in my eyes it's just not distinct enough from native comments given the reuse of multiple "#" characters with each other and intermixing of comments (imagine a scenario where code highlighting is not working).

Seems like a decent middle-ground option could be the commented TOML-style bracket sections headings approach.

• Section heading is a comment line that starts with # [Section].

• Nesting of Section Levels could possibly be handled by the number of enclosing brackets of the Section header

Example:

# [Services]                 # Top-Level Section
DB_TIMEOUT=30

# [[Backend]]               # Level 2 Sub-Section
DB_URL=
DB_USER=

# [[Auth]]                  # Sibling of Backend sub-section, still level 2
JWT_SECRET=

# [Observability]           # New Top-Level Section
LOG_LEVEL=info

...

Optional explicit section closing tag:
If a user ever needs to close a section early or a user just prefers explicit section closures, allow usage of a # [/Section] or # [!Section] closing tag, which closes the most recent open same-named section at its level.

Also allows for usage like:

# [Services]

DB_TIMEOUT=30

# [[Backend]]
DB_URL=
DB_USER=

# [[Auth]]
JWT_SECRET=

# [/Services]

# [Observability]
LOG_LEVEL=info

...

But prefer implicit section closing for readability. Could also lint if explicit close is redundant.

---

However if you are dead-set on keeping the proposed markdown-style "#" usage approach, then at least consider having it utilize a space delimiter or something to separate it from the native comment "#" character , so something like:

# ## Services

# ### Backend
DB_URL=

# ### Auth
JWT_SECRET=
...