Skip to content

Commit 8da5845

Browse files
ricksaargericksaarge
authored
docs: add v1.1.0 frontmatter enhancements and modular spec (#4)
* docs: add v1.1.0 frontmatter enhancements and modular spec (#3) * docs: add v1.1.0 frontmatter documentation and split spec - Add date_format frontmatter field documentation - Add field behavior table (locale, timezone, date_format) - Document file-scoped frontmatter (no inheritance to linked files) - Split specification.md into modular detail files: - spec/frontmatter.md: field behavior, processing, file scope - spec/examples.md: date/time, YAML, multi-file examples - spec/libraries.md: library stack and processing pipeline - spec/compatibility.md: todo.txt, todo.md, xit conversion - Reduce specification.md from 656 to 508 lines (under AISD 600 limit) - Remove specification.md exclusion from AISD line count checks - Update AGENTS.md with frontmatter section * chore: remove completed v1.1.0 items from TODO * docs: add v1.1.0 frontmatter enhancements and modular spec - Add date_format frontmatter field for custom output formatting - Add field behavior table (locale, timezone, date_format) - Document file-scoped frontmatter (no inheritance to linked files) - Split specification.md into modular detail files: - spec/frontmatter.md: field behavior, processing, file scope - spec/examples.md: date/time, YAML, multi-file examples - spec/libraries.md: library stack and processing pipeline - spec/compatibility.md: todo.txt, todo.md, xit conversion - Reduce specification.md from 656 to 508 lines (under AISD 600 limit) - Configure semantic-release: docs=minor for spec repos - Update AGENTS.md with frontmatter section * chore: auto-update version in markdown files on release Configure semantic-release to sed-replace version strings in specification.md, README.md, and AGENTS.md during releases. * fix: add missing conventional-changelog-conventionalcommits package
1 parent 3dfe2c3 commit 8da5845

9 files changed

Lines changed: 541 additions & 128 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525
node-version: "20"
2626

2727
- name: Install semantic-release
28-
run: npm install -g semantic-release @semantic-release/changelog @semantic-release/git
28+
run: npm install -g semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/exec conventional-changelog-conventionalcommits
2929

3030
- name: Run semantic-release
3131
env:

‎.releaserc.json‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,37 @@
11
{
22
"branches": ["main"],
33
"plugins": [
4-
"@semantic-release/commit-analyzer",
4+
[
5+
"@semantic-release/commit-analyzer",
6+
{
7+
"preset": "conventionalcommits",
8+
"releaseRules": [
9+
{ "type": "docs", "release": "minor" },
10+
{ "type": "fix", "release": "patch" },
11+
{ "type": "refactor", "release": "patch" },
12+
{ "type": "style", "release": "patch" },
13+
{ "type": "perf", "release": "patch" },
14+
{ "type": "chore", "release": false }
15+
]
16+
}
17+
],
518
"@semantic-release/release-notes-generator",
619
[
720
"@semantic-release/changelog",
821
{
922
"changelogFile": "CHANGELOG.md"
1023
}
1124
],
25+
[
26+
"@semantic-release/exec",
27+
{
28+
"prepareCmd": "sed -i 's/\\*\\*Version:\\*\\* [0-9]*\\.[0-9]*\\.[0-9]*/\\*\\*Version:\\*\\* ${nextRelease.version}/' docs/specification.md && sed -i 's/Draft v[0-9]*\\.[0-9]*\\.[0-9]*/Draft v${nextRelease.version}/g' README.md AGENTS.md"
29+
}
30+
],
1231
[
1332
"@semantic-release/git",
1433
{
15-
"assets": ["CHANGELOG.md"],
34+
"assets": ["CHANGELOG.md", "docs/specification.md", "README.md", "AGENTS.md"],
1635
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
1736
}
1837
],

‎AGENTS.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,23 @@ taskmark-spec/
149149

150150
**Invalid Date Handling:** Warn at `file:line`, ignore field, continue parsing
151151

152+
### YAML Front Matter
153+
154+
**Supported Fields:**
155+
156+
| Field | Purpose | Example |
157+
|-------|---------|---------|
158+
| `locale` | Natural language date parsing + default output format | `en_US`, `fr_FR` |
159+
| `timezone` | Default timezone for dates without explicit timezone | `America/New_York`, `UTC` |
160+
| `date_format` | Output date format (strftime), overrides locale | `%Y-%m-%d`, `%d/%m/%Y` |
161+
162+
**File Scope Rules:**
163+
164+
- Front matter applies ONLY to the current file
165+
- Linked files retain their own front matter
166+
- No inheritance of front matter between files
167+
- Default: system locale/timezone, ISO 8601 output (`YYYY-MM-DD`)
168+
152169
### Section Headers and Inheritance
153170

154171
```markdown

‎TODO.md‎

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,6 @@
22

33
Project roadmap and tasks for the TaskMark specification.
44

5-
## v1.1.0 - Frontmatter Enhancements +taskmark-spec/v1.1.0 #documentation
6-
7-
### Locale and Date Handling
8-
9-
- [ ] Document `locale` frontmatter field ~2h
10-
- Used for parsing natural language dates and recurrence patterns
11-
- When set (without `date_format`), output uses locale's default date format instead of ISO
12-
- [ ] Document `date_format` frontmatter field ~1h
13-
- Accepts strftime patterns (e.g., `%d/%m/%Y`)
14-
- Overrides locale default format when both are set
15-
- [ ] Document that default output format is ISO 8601 (`YYYY-MM-DD`) when no locale/date_format set ~30m
16-
17-
### File-Scoped Frontmatter
18-
19-
- [ ] Document that `timezone` only applies to the current file ~30m
20-
- [ ] Document that `locale` only applies to the current file ~30m
21-
- [ ] Document that `date_format` only applies to the current file ~30m
22-
- [ ] Document that imported files retain their own frontmatter settings ~1h
23-
245
## v1.2.0 - Documentation Updates +taskmark-spec/v1.2.0 #documentation
256

267
- [ ] Document `@user` assignees in headers for inheritance ~1h

‎docs/spec/compatibility.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Format Compatibility
2+
3+
Conversion rules between TaskMark and other task formats. See [specification.md](../specification.md) for the core spec.
4+
5+
---
6+
7+
## todo.txt Conversion
8+
9+
| Element | todo.txt | TaskMark | Conversion Rule |
10+
|---------|----------|---------|----------------|
11+
| Priority | `(A)` at start | `(A)` after state | Move after `- [ ]` |
12+
| Contexts | `@context` | `#context` | Replace `@` with `#` |
13+
| Projects | `+project` | `+project` | No change |
14+
| Assignees | Not supported | `@user` | Add if needed |
15+
| Dates | Creation date required | Optional | Remove if unwanted |
16+
| Sections | Not supported | `## Section` | Group by project |
17+
18+
### Example Conversion
19+
20+
**todo.txt:**
21+
22+
```
23+
(A) 2024-03-10 Call client +Sales @phone due:2024-03-15
24+
x 2024-03-05 2024-03-01 Complete report +Reports
25+
```
26+
27+
**TaskMark:**
28+
29+
```markdown
30+
# TODO
31+
32+
## Sales
33+
- [ ] (A) 2024-03-10 Call client +Sales #phone due:2024-03-15
34+
35+
## Reports
36+
- [x] 2024-03-01 2024-03-05 Complete report +Reports
37+
```
38+
39+
---
40+
41+
## todo.md Conversion
42+
43+
| Element | todo.md | TaskMark | Conversion Rule |
44+
|---------|---------|---------|----------------|
45+
| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed |
46+
| Priority | Not standardized | `(value)` after state | Add if needed |
47+
| Metadata | Freeform | `key:value` | Standardize format |
48+
| Recurrence | Not supported | `repeat:PATTERN` | Add if needed |
49+
| File links | Not supported | `[text](file.md)` | Add if needed |
50+
51+
### Example Conversion
52+
53+
**todo.md:**
54+
55+
```markdown
56+
# Tasks
57+
58+
- [ ] Important task
59+
- [x] Completed task
60+
- [-] Cancelled task
61+
```
62+
63+
**TaskMark:**
64+
65+
```markdown
66+
# TODO
67+
68+
## Tasks
69+
- [ ] (A) Important task
70+
- [x] Completed task
71+
- [-] Cancelled task
72+
```
73+
74+
---
75+
76+
## xit Conversion
77+
78+
| Element | xit | TaskMark | Conversion Rule |
79+
|---------|-----|---------|----------------|
80+
| Date headers | `2024-03-15` | `## Section` | Convert to sections |
81+
| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed |
82+
| Metadata | `key:value` | `key:value` | Extract core fields |
83+
| Priority | Not supported | `(value)` | Add if needed |
84+
| Projects | `project:name` | `+name` | Convert syntax |
85+
86+
### Example Conversion
87+
88+
**xit:**
89+
90+
```
91+
2024-03-15
92+
[ ] Deploy to staging project:Backend
93+
[x] Write tests project:Backend
94+
[-] Skip documentation
95+
```
96+
97+
**TaskMark:**
98+
99+
```markdown
100+
# TODO
101+
102+
## 2024-03-15
103+
- [ ] Deploy to staging +Backend
104+
- [x] Write tests +Backend
105+
- [-] Skip documentation
106+
```
107+
108+
---
109+
110+
## Bidirectional Conversion Notes
111+
112+
| Direction | Data Loss | Notes |
113+
|-----------|-----------|-------|
114+
| todo.txt → TaskMark | None | Full compatibility |
115+
| TaskMark → todo.txt | Sections, blocked state, subtasks | Use project tags for sections |
116+
| todo.md → TaskMark | None | Full compatibility |
117+
| TaskMark → todo.md | Priority, metadata, recurrence | Lossy conversion |
118+
| xit → TaskMark | None | Full compatibility |
119+
| TaskMark → xit | Sections, assignees | Use date headers |

‎docs/spec/examples.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# TaskMark Examples
2+
3+
Detailed examples for the TaskMark format. See [specification.md](../specification.md) for the core spec.
4+
5+
---
6+
7+
## Minimal
8+
9+
```markdown
10+
# TODO
11+
- [ ] Task
12+
```
13+
14+
---
15+
16+
## Full Featured
17+
18+
```markdown
19+
# TODO +Acme #work
20+
21+
## Backend Operations +Backend #critical
22+
23+
- [ ] (A) 2024-03-10 Fix database connection @alice +Database due:2024-03-15T18:00 ~8h type:urgent ticket:ENG-4739 created:2024-03-01T10:00 started:2024-03-10T09:00
24+
- [ ] (B) 2024-03-10 Update connection pooling @alice ~2h
25+
- [ ] (B) 2024-03-11 Add retry logic @bob ~3h
26+
- [x] (C) 2024-03-09 2024-03-10 Write migration @alice ~3h
27+
28+
- [ ] 2024-03-15T09:00 Daily status report @alice repeat:"weekdays at 9am" due:2024-03-15T09:30 ~30m type:report
29+
```
30+
31+
**After Inheritance:**
32+
33+
- First task: `+Acme/Backend/Database`, `#work`, `#critical`
34+
- Subtasks: Inherit parent + section + top-level metadata
35+
- Daily report: `+Acme/Backend`, `#work`, `#critical`
36+
37+
---
38+
39+
## Date and Time Examples
40+
41+
```markdown
42+
# TODO +MyProject
43+
44+
## Date-only
45+
- [ ] (A) 2024-03-10 Start project planning
46+
- [x] (B) 2024-03-01 2024-03-05 Complete requirements
47+
48+
## Time-specific
49+
- [ ] 2024-03-15T09:00 Morning standup due:2024-03-15T09:30
50+
- [ ] 2024-03-15T14:00 Client presentation due:2024-03-15T15:00
51+
52+
## With timezones
53+
- [ ] 2024-03-15T09:00-05:00 Team call (EST)
54+
- [ ] 2024-03-15T15:00+01:00 European meeting
55+
56+
## Full lifecycle
57+
- [ ] (A) 2024-03-10T09:00 Implement OAuth2 @alice created:2024-03-01T10:00 started:2024-03-10T09:00 due:2024-03-15T18:00
58+
59+
## Recurring
60+
- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am"
61+
- [ ] 2024-04-01 Monthly review repeat:"first day of month"
62+
```
63+
64+
**Result:** All tasks inherit `+MyProject` from top-level section.
65+
66+
---
67+
68+
## YAML Front Matter
69+
70+
```markdown
71+
---
72+
locale: en_US
73+
timezone: America/New_York
74+
---
75+
76+
# TODO
77+
78+
## Meetings
79+
- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am"
80+
- [ ] 2024-04-01 Monthly review repeat:"first day of month"
81+
82+
## Tasks
83+
- [ ] (A) 2024-03-10 Start development @alice due:2024-03-15T17:00
84+
```
85+
86+
**Result:** All datetimes without explicit timezone use `America/New_York` (EST/EDT).
87+
88+
---
89+
90+
## Custom Date Format
91+
92+
```markdown
93+
---
94+
locale: en_GB
95+
date_format: "%d/%m/%Y"
96+
timezone: Europe/London
97+
---
98+
99+
# TODO
100+
101+
- [ ] 10/03/2024 Project kickoff @alice
102+
- [x] 01/03/2024 05/03/2024 Complete requirements @bob
103+
```
104+
105+
**Result:** Dates are output in day/month/year format. The `date_format` overrides the locale default.
106+
107+
---
108+
109+
## Multi-File with Different Front Matter
110+
111+
**main.md:**
112+
113+
```markdown
114+
---
115+
timezone: America/New_York
116+
date_format: "%Y-%m-%d"
117+
---
118+
119+
# TODO +Project
120+
121+
## Engineering +Engineering
122+
[UK Team](uk-team.md)
123+
```
124+
125+
**uk-team.md:**
126+
127+
```markdown
128+
---
129+
timezone: Europe/London
130+
date_format: "%d/%m/%Y"
131+
---
132+
133+
# UK Team Tasks
134+
135+
- [ ] 15/03/2024 Sprint planning @alice
136+
```
137+
138+
**Result:** Each file uses its own front matter. The UK team file displays dates in `dd/mm/yyyy` format with London timezone, independent of the parent file's settings.

0 commit comments

Comments
 (0)