Skip to content

format-spec.md

Latest commit

 

History

History
279 lines (199 loc) · 8.4 KB

format-spec.md

File metadata and controls

279 lines (199 loc) · 8.4 KB

Hexfield Text Formatting Standard

Version 1.0 | Canonical reference for the Hexfield planner file format.

This document is the source of truth. Other Hexfield ecosystem repos (Hexfield Deck, future tools) should reference this spec rather than re-documenting the format.

1. File Identity

A Hexfield planner file is a standard markdown file (.md) with a YAML frontmatter block containing type: hexfield-planner:

---
type: hexfield-planner
---

This single field is the canonical activation signal. Tools in the Hexfield ecosystem use it to scope their behavior — no other heuristics required.

Files without type: hexfield-planner are ordinary markdown and must never be affected by Hexfield tooling.

2. Frontmatter Fields

The following YAML frontmatter keys are recognized by the Hexfield ecosystem. Only type is required; the rest are optional and context-dependent.

Key Required Description
type Yes Must be hexfield-planner. File identity signal.
week No ISO week number (1–53). Used by Hexfield Deck for weekly planners.
year No Four-digit year.
quarter No Quarter label (e.g., Q1, Q2).
tags No YAML list of tags (e.g., [planner, weekly]).
startDate No Start date in YYYY-MM-DD format.
endDate No End date in YYYY-MM-DD format.

Example:

---
type: hexfield-planner
week: 14
year: 2026
quarter: Q2
tags: [planner, weekly]
startDate: 2026-04-05
endDate: 2026-04-11
---

3. Inline Tokens

Inline tokens are metadata markers that appear within task lines (list items). A typical task line looks like:

- [ ] Ship parser v1 #hexfield [2026-04-10] !!! est:4h // needs review

3.1 Project Tags

Syntax Scope
#project-name entity.name.tag.hexfield
  • The # must be preceded by whitespace or appear at the start of text.
  • Tag names may contain letters, digits, hyphens, and underscores: [a-zA-Z][a-zA-Z0-9_-]*
  • A # inside a URL is never treated as a project tag.

Default color: Blue (#569CD6)

3.2 Due Dates

Syntax Form Scope
[YYYY-MM-DD] Bracketed (canonical) string.quoted.hexfield.date
due:YYYY-MM-DD Prefix (alternate) string.quoted.hexfield.date

The bracketed form [YYYY-MM-DD] is the preferred syntax. The due: prefix form is supported by the Hexfield Deck parser for compatibility.

Due dates are dynamically colored by proximity to today:

Proximity Color Hex
Overdue (date < today) Red #F44747
Today Orange #CE9178
Within 3 days Yellow #CCA700
Future (4+ days) Gray #858585

Colors update dynamically as the date approaches.

3.3 Priority

Syntax Level Color Hex
!!! High Red #F44747
!! Medium Yellow #CCA700
! Low Green #89D185
  • Priority markers must not be preceded or followed by another !.
  • Must not be preceded by a letter (avoids false positives in prose).

Scope: keyword.operator.hexfield.priority.{high,medium,low}

3.4 Time Estimates

Syntax Example Scope
est:Xh est:4h constant.numeric.hexfield.estimate
est:Xm est:30m constant.numeric.hexfield.estimate
est:X.Xh est:1.5h constant.numeric.hexfield.estimate
  • X is one or more digits; decimal values are supported (est:1.5h).
  • h = hours, m = minutes. No other units.

Default color: Teal (#4EC9B0)

3.5 Checkbox States

Hexfield planner files use standard markdown checkboxes with one extension:

Syntax State Color Hex
[ ] To Do Default (no override) —
[/] In Progress Orange #CE9178
[x] Done Dimmed #6B737C
  • [/] is the Hexfield-specific extension to standard markdown checkboxes. It must appear in checkbox position: immediately after a list marker (- , * , + ).
  • [x] done tasks may be styled with strikethrough and a dimmed color to visually de-emphasize completed work.

Scopes:

  • [/] — markup.changed.hexfield.checkbox
  • [x] — styled via Decoration API (not grammar)

3.6 Line Comments

Syntax Example Scope
// text // needs review comment.line.double-slash.hexfield
  • The // must be preceded by whitespace (text // comment).
  • Everything from // to end of line is the comment.
  • Comments are stripped by parsers before extracting other metadata.

Default color: Green (#6A9955)

4. Token Extraction Order

When parsing a task line, metadata should be extracted in this order:

  1. Line comment (// ...) — strip first so comments don't interfere
  2. Project tag (#name)
  3. Due date ([YYYY-MM-DD] or due:YYYY-MM-DD)
  4. Priority (!!! / !! / !)
  5. Time estimate (est:Xh)

After extraction, the remaining text is the task's clean title.

5. Color Configuration

All token colors are user-configurable through a shared configuration namespace: hexfield.colors.*

This namespace is owned by Hexfield Text. Other Hexfield extensions read from it (with fallback defaults) but do not register it.

Setting Default Token
hexfield.colors.projectTag #569CD6 #project tags
hexfield.colors.priorityHigh #F44747 !!!
hexfield.colors.priorityMed #CCA700 !!
hexfield.colors.priorityLow #89D185 !
hexfield.colors.timeEstimate #4EC9B0 est:Xh / est:Xm
hexfield.colors.inProgressCheckbox #CE9178 [/]
hexfield.colors.doneTask #6B737C [x] (with strikethrough)
hexfield.colors.lineComment #6A9955 // comment
hexfield.colors.dueDateOverdue #F44747 Overdue dates
hexfield.colors.dueDateToday #CE9178 Due today
hexfield.colors.dueDateSoon #CCA700 Due within 3 days
hexfield.colors.dueDateFuture #858585 Future dates

Shared Color Palette

The following 12 colors form the curated swatch set used across the ecosystem (e.g., Hexfield Deck's project color picker). Tools that offer color selection should use these swatches for visual consistency.

#569CD6  #4EC9B0  #89D185  #6A9955
#CCA700  #DCDCAA  #CE9178  #F44747
#F92672  #C586C0  #9CDCFE  #858585

6. Language ID

Hexfield Text promotes planner files to a custom VS Code language ID:

hexfield-markdown

This is how colorization is scoped exclusively to Hexfield planner files without leaking onto regular markdown.

Other Hexfield extensions must accept both markdown and hexfield-markdown as valid language IDs:

"when": "resourceLangId == markdown || resourceLangId == hexfield-markdown"

7. Ecosystem Integration

Who Owns What

Namespace Owner Others may
hexfield.colors.* Hexfield Text Read (with fallback defaults)
hexfield-deck.projects Hexfield Deck Read and write
hexfield-markdown language ID Hexfield Text Accept alongside markdown
type: hexfield-planner frontmatter Shared convention Check to scope activation

Design Principles

  • Independently installable. Each component works alone.
  • Loosely coupled. Components coordinate through shared config, not APIs.
  • Same file, different views. Every component is a different lens on the same markdown file.

8. Implementation Notes

Known Gaps (as of v1.0)

These are acknowledged discrepancies between the standard and current implementations. They should be resolved in future releases.

Gap Hexfield Text Hexfield Deck
due:YYYY-MM-DD highlighting Not highlighted (parser-only in Deck) Supported in parser
est:1.5h decimal estimates Supported in grammar Parser regex needs update (\d+[hm] → \d+(?:\.\d+)?[hm])
[x] done task styling Color config exists; decoration not yet wired N/A (board handles its own styling)

Revision History

Version Date Changes
1.0 2026-04-05 Initial standard — consolidated from Hexfield Text USER_GUIDE, Hexfield Deck ecosystem docs, and parser implementation

This document lives in the Hexfield Text repository. It is the canonical reference for the Hexfield planner file format. Other Hexfield ecosystem repos should link here rather than duplicating format documentation.