diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 101a2cb..a6c42eb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,7 +25,7 @@ jobs: node-version: "20" - name: Install semantic-release - run: npm install -g semantic-release @semantic-release/changelog @semantic-release/git + run: npm install -g semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/exec conventional-changelog-conventionalcommits - name: Run semantic-release env: diff --git a/.releaserc.json b/.releaserc.json index 8ee5c68..0eb91d8 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -1,7 +1,20 @@ { "branches": ["main"], "plugins": [ - "@semantic-release/commit-analyzer", + [ + "@semantic-release/commit-analyzer", + { + "preset": "conventionalcommits", + "releaseRules": [ + { "type": "docs", "release": "minor" }, + { "type": "fix", "release": "patch" }, + { "type": "refactor", "release": "patch" }, + { "type": "style", "release": "patch" }, + { "type": "perf", "release": "patch" }, + { "type": "chore", "release": false } + ] + } + ], "@semantic-release/release-notes-generator", [ "@semantic-release/changelog", @@ -9,10 +22,16 @@ "changelogFile": "CHANGELOG.md" } ], + [ + "@semantic-release/exec", + { + "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" + } + ], [ "@semantic-release/git", { - "assets": ["CHANGELOG.md"], + "assets": ["CHANGELOG.md", "docs/specification.md", "README.md", "AGENTS.md"], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" } ], diff --git a/AGENTS.md b/AGENTS.md index 6f97e7c..29d57a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,6 +149,23 @@ taskmark-spec/ **Invalid Date Handling:** Warn at `file:line`, ignore field, continue parsing +### YAML Front Matter + +**Supported Fields:** + +| Field | Purpose | Example | +|-------|---------|---------| +| `locale` | Natural language date parsing + default output format | `en_US`, `fr_FR` | +| `timezone` | Default timezone for dates without explicit timezone | `America/New_York`, `UTC` | +| `date_format` | Output date format (strftime), overrides locale | `%Y-%m-%d`, `%d/%m/%Y` | + +**File Scope Rules:** + +- Front matter applies ONLY to the current file +- Linked files retain their own front matter +- No inheritance of front matter between files +- Default: system locale/timezone, ISO 8601 output (`YYYY-MM-DD`) + ### Section Headers and Inheritance ```markdown diff --git a/TODO.md b/TODO.md index 9ff6085..53a1893 100644 --- a/TODO.md +++ b/TODO.md @@ -2,25 +2,6 @@ Project roadmap and tasks for the TaskMark specification. -## v1.1.0 - Frontmatter Enhancements +taskmark-spec/v1.1.0 #documentation - -### Locale and Date Handling - -- [ ] Document `locale` frontmatter field ~2h - - Used for parsing natural language dates and recurrence patterns - - When set (without `date_format`), output uses locale's default date format instead of ISO -- [ ] Document `date_format` frontmatter field ~1h - - Accepts strftime patterns (e.g., `%d/%m/%Y`) - - Overrides locale default format when both are set -- [ ] Document that default output format is ISO 8601 (`YYYY-MM-DD`) when no locale/date_format set ~30m - -### File-Scoped Frontmatter - -- [ ] Document that `timezone` only applies to the current file ~30m -- [ ] Document that `locale` only applies to the current file ~30m -- [ ] Document that `date_format` only applies to the current file ~30m -- [ ] Document that imported files retain their own frontmatter settings ~1h - ## v1.2.0 - Documentation Updates +taskmark-spec/v1.2.0 #documentation - [ ] Document `@user` assignees in headers for inheritance ~1h diff --git a/docs/spec/compatibility.md b/docs/spec/compatibility.md new file mode 100644 index 0000000..f3d84f5 --- /dev/null +++ b/docs/spec/compatibility.md @@ -0,0 +1,119 @@ +# Format Compatibility + +Conversion rules between TaskMark and other task formats. See [specification.md](../specification.md) for the core spec. + +--- + +## todo.txt Conversion + +| Element | todo.txt | TaskMark | Conversion Rule | +|---------|----------|---------|----------------| +| Priority | `(A)` at start | `(A)` after state | Move after `- [ ]` | +| Contexts | `@context` | `#context` | Replace `@` with `#` | +| Projects | `+project` | `+project` | No change | +| Assignees | Not supported | `@user` | Add if needed | +| Dates | Creation date required | Optional | Remove if unwanted | +| Sections | Not supported | `## Section` | Group by project | + +### Example Conversion + +**todo.txt:** + +``` +(A) 2024-03-10 Call client +Sales @phone due:2024-03-15 +x 2024-03-05 2024-03-01 Complete report +Reports +``` + +**TaskMark:** + +```markdown +# TODO + +## Sales +- [ ] (A) 2024-03-10 Call client +Sales #phone due:2024-03-15 + +## Reports +- [x] 2024-03-01 2024-03-05 Complete report +Reports +``` + +--- + +## todo.md Conversion + +| Element | todo.md | TaskMark | Conversion Rule | +|---------|---------|---------|----------------| +| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed | +| Priority | Not standardized | `(value)` after state | Add if needed | +| Metadata | Freeform | `key:value` | Standardize format | +| Recurrence | Not supported | `repeat:PATTERN` | Add if needed | +| File links | Not supported | `[text](file.md)` | Add if needed | + +### Example Conversion + +**todo.md:** + +```markdown +# Tasks + +- [ ] Important task +- [x] Completed task +- [-] Cancelled task +``` + +**TaskMark:** + +```markdown +# TODO + +## Tasks +- [ ] (A) Important task +- [x] Completed task +- [-] Cancelled task +``` + +--- + +## xit Conversion + +| Element | xit | TaskMark | Conversion Rule | +|---------|-----|---------|----------------| +| Date headers | `2024-03-15` | `## Section` | Convert to sections | +| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed | +| Metadata | `key:value` | `key:value` | Extract core fields | +| Priority | Not supported | `(value)` | Add if needed | +| Projects | `project:name` | `+name` | Convert syntax | + +### Example Conversion + +**xit:** + +``` +2024-03-15 +[ ] Deploy to staging project:Backend +[x] Write tests project:Backend +[-] Skip documentation +``` + +**TaskMark:** + +```markdown +# TODO + +## 2024-03-15 +- [ ] Deploy to staging +Backend +- [x] Write tests +Backend +- [-] Skip documentation +``` + +--- + +## Bidirectional Conversion Notes + +| Direction | Data Loss | Notes | +|-----------|-----------|-------| +| todo.txt → TaskMark | None | Full compatibility | +| TaskMark → todo.txt | Sections, blocked state, subtasks | Use project tags for sections | +| todo.md → TaskMark | None | Full compatibility | +| TaskMark → todo.md | Priority, metadata, recurrence | Lossy conversion | +| xit → TaskMark | None | Full compatibility | +| TaskMark → xit | Sections, assignees | Use date headers | diff --git a/docs/spec/examples.md b/docs/spec/examples.md new file mode 100644 index 0000000..453b054 --- /dev/null +++ b/docs/spec/examples.md @@ -0,0 +1,138 @@ +# TaskMark Examples + +Detailed examples for the TaskMark format. See [specification.md](../specification.md) for the core spec. + +--- + +## Minimal + +```markdown +# TODO +- [ ] Task +``` + +--- + +## Full Featured + +```markdown +# TODO +Acme #work + +## Backend Operations +Backend #critical + +- [ ] (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 + - [ ] (B) 2024-03-10 Update connection pooling @alice ~2h + - [ ] (B) 2024-03-11 Add retry logic @bob ~3h + - [x] (C) 2024-03-09 2024-03-10 Write migration @alice ~3h + +- [ ] 2024-03-15T09:00 Daily status report @alice repeat:"weekdays at 9am" due:2024-03-15T09:30 ~30m type:report +``` + +**After Inheritance:** + +- First task: `+Acme/Backend/Database`, `#work`, `#critical` +- Subtasks: Inherit parent + section + top-level metadata +- Daily report: `+Acme/Backend`, `#work`, `#critical` + +--- + +## Date and Time Examples + +```markdown +# TODO +MyProject + +## Date-only +- [ ] (A) 2024-03-10 Start project planning +- [x] (B) 2024-03-01 2024-03-05 Complete requirements + +## Time-specific +- [ ] 2024-03-15T09:00 Morning standup due:2024-03-15T09:30 +- [ ] 2024-03-15T14:00 Client presentation due:2024-03-15T15:00 + +## With timezones +- [ ] 2024-03-15T09:00-05:00 Team call (EST) +- [ ] 2024-03-15T15:00+01:00 European meeting + +## Full lifecycle +- [ ] (A) 2024-03-10T09:00 Implement OAuth2 @alice created:2024-03-01T10:00 started:2024-03-10T09:00 due:2024-03-15T18:00 + +## Recurring +- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am" +- [ ] 2024-04-01 Monthly review repeat:"first day of month" +``` + +**Result:** All tasks inherit `+MyProject` from top-level section. + +--- + +## YAML Front Matter + +```markdown +--- +locale: en_US +timezone: America/New_York +--- + +# TODO + +## Meetings +- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am" +- [ ] 2024-04-01 Monthly review repeat:"first day of month" + +## Tasks +- [ ] (A) 2024-03-10 Start development @alice due:2024-03-15T17:00 +``` + +**Result:** All datetimes without explicit timezone use `America/New_York` (EST/EDT). + +--- + +## Custom Date Format + +```markdown +--- +locale: en_GB +date_format: "%d/%m/%Y" +timezone: Europe/London +--- + +# TODO + +- [ ] 10/03/2024 Project kickoff @alice +- [x] 01/03/2024 05/03/2024 Complete requirements @bob +``` + +**Result:** Dates are output in day/month/year format. The `date_format` overrides the locale default. + +--- + +## Multi-File with Different Front Matter + +**main.md:** + +```markdown +--- +timezone: America/New_York +date_format: "%Y-%m-%d" +--- + +# TODO +Project + +## Engineering +Engineering +[UK Team](uk-team.md) +``` + +**uk-team.md:** + +```markdown +--- +timezone: Europe/London +date_format: "%d/%m/%Y" +--- + +# UK Team Tasks + +- [ ] 15/03/2024 Sprint planning @alice +``` + +**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. diff --git a/docs/spec/frontmatter.md b/docs/spec/frontmatter.md new file mode 100644 index 0000000..1fc4af9 --- /dev/null +++ b/docs/spec/frontmatter.md @@ -0,0 +1,128 @@ +# YAML Front Matter + +Detailed documentation for TaskMark YAML front matter. See [specification.md](../specification.md) for the core spec. + +--- + +## Position and Syntax + +| Constraint | Rule | +|-----------|------| +| Position | MUST appear at file start | +| Delimiters | MUST be enclosed between `---` lines | +| Syntax | MUST be valid YAML | +| Invalid YAML | MUST warn, MUST NOT fail parsing | +| Unknown fields | MUST be ignored | + +--- + +## Supported Fields + +| Field | Type | Constraint | Purpose | Example Values | +|-------|------|-----------|---------|----------------| +| `locale` | String | OPTIONAL | Locale for dateparser/recurrent | `en_US`, `fr_FR`, `de_DE` | +| `timezone` | String | OPTIONAL | Default timezone for datetime fields | `America/New_York`, `Europe/Paris`, `UTC` | +| `date_format` | String | OPTIONAL | Output date format (strftime pattern) | `%Y-%m-%d`, `%d/%m/%Y`, `%B %d, %Y` | + +--- + +## Field Behavior + +| Field | Input Parsing | Output Formatting | +|-------|--------------|-------------------| +| `locale` | Used by dateparser for natural language | If set alone, uses locale's default date format | +| `timezone` | Applied to dates without explicit timezone | Applied when serializing dates | +| `date_format` | Not used for parsing | Overrides locale default when both are set | + +**Default Output Format:** ISO 8601 (`YYYY-MM-DD`) when no `locale` or `date_format` is set. + +--- + +## Processing Order + +1. Parse YAML front matter (if present) +2. Extract `locale`, `timezone`, and `date_format` values +3. Apply to all subsequent date/time parsing in THIS FILE ONLY + +--- + +## File Scope + +| Rule | Constraint | +|------|-----------| +| Scope | Front matter settings apply ONLY to the current file | +| Linked files | Imported files via `[Link](file.md)` retain their own front matter | +| No inheritance | Parent file front matter does NOT cascade to linked files | +| Default behavior | Files without front matter use system locale/timezone and ISO 8601 output | + +--- + +## Examples + +### Basic Usage + +```markdown +--- +locale: en_US +timezone: America/New_York +--- + +# TODO + +## Meetings +- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am" +- [ ] 2024-04-01 Monthly review repeat:"first day of month" + +## Tasks +- [ ] (A) 2024-03-10 Start development @alice due:2024-03-15T17:00 +``` + +**Result:** All datetimes without explicit timezone use `America/New_York` (EST/EDT). + +### Custom Date Format + +```markdown +--- +locale: en_GB +date_format: "%d/%m/%Y" +timezone: Europe/London +--- + +# TODO + +- [ ] 10/03/2024 Project kickoff @alice +- [x] 01/03/2024 05/03/2024 Complete requirements @bob +``` + +**Result:** Dates are output in day/month/year format. The `date_format` overrides the locale default. + +### Multi-File with Different Front Matter + +**main.md:** + +```markdown +--- +timezone: America/New_York +date_format: "%Y-%m-%d" +--- + +# TODO +Project + +## Engineering +Engineering +[UK Team](uk-team.md) +``` + +**uk-team.md:** + +```markdown +--- +timezone: Europe/London +date_format: "%d/%m/%Y" +--- + +# UK Team Tasks + +- [ ] 15/03/2024 Sprint planning @alice +``` + +**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. diff --git a/docs/spec/libraries.md b/docs/spec/libraries.md new file mode 100644 index 0000000..2221a14 --- /dev/null +++ b/docs/spec/libraries.md @@ -0,0 +1,91 @@ +# Library Stack + +Required libraries for TaskMark implementations. See [specification.md](../specification.md) for the core spec. + +--- + +## Required Libraries + +| Purpose | Library | Version | Usage | +|---------|---------|---------|-------| +| Natural language → datetime | [dateparser](https://dateparser.readthedocs.io/) | Latest | Parse phrases like "next Friday 3pm" | +| Natural language → recurrence | [recurrent](https://github.com/kvh/recurrent) | Latest | Parse "every Tuesday" into RRULE | +| Recurrence → dates | [python-dateutil](https://dateutil.readthedocs.io/) | Latest | Generate occurrence dates from RRULE | +| Datetime wrapper | [pendulum](https://pendulum.eustace.io/) | Latest | Timezone-aware datetime operations | + +--- + +## Processing Pipeline + +| Step | Input | Library | Output | +|------|-------|---------|--------| +| 1 | Natural language date | dateparser | Datetime object | +| 2 | Natural language recurrence | recurrent | RRULE string | +| 3 | RRULE string | python-dateutil | List of datetime objects | +| 4 | Datetime object | pendulum | Timezone-aware datetime | + +--- + +## Library Details + +### dateparser + +Parses natural language date expressions into datetime objects. + +**Capabilities:** + +- Multi-language support (50+ languages) +- Relative dates: "tomorrow", "next week", "in 3 days" +- Absolute dates: "March 15, 2024", "15/03/2024" +- Time expressions: "3pm", "15:00", "noon" + +**Usage in TaskMark:** + +- Parsing natural language dates in task descriptions +- Respecting `locale` from YAML front matter + +### recurrent + +Parses natural language recurrence patterns into RRULE strings. + +**Capabilities:** + +- Pattern recognition: "every Tuesday", "daily", "weekly" +- Complex patterns: "first Monday of month", "every other week" +- Output: iCalendar RRULE format + +**Usage in TaskMark:** + +- Parsing `repeat:` field values +- Converting to RRULE for date calculation + +### python-dateutil + +Generates occurrence dates from RRULE strings. + +**Capabilities:** + +- Full RRULE support (RFC 5545) +- Date iteration: next occurrence, all occurrences in range +- Timezone handling + +**Usage in TaskMark:** + +- Calculating next occurrence when task is completed +- Generating future task instances + +### pendulum + +Timezone-aware datetime wrapper with intuitive API. + +**Capabilities:** + +- Timezone conversion +- Date arithmetic +- Formatting with locale support + +**Usage in TaskMark:** + +- Applying `timezone` from YAML front matter +- Date offset calculations for recurring tasks +- Formatting output dates diff --git a/docs/specification.md b/docs/specification.md index 90d5443..1b9de42 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -24,21 +24,18 @@ | Position | MUST appear at file start | | Delimiters | MUST be enclosed between `---` lines | | Syntax | MUST be valid YAML | -| Invalid YAML | SHOULD warn, MUST NOT fail parsing | +| Invalid YAML | MUST warn, MUST NOT fail parsing | | Unknown fields | MUST be ignored | **Supported Fields:** -| Field | Type | Constraint | Purpose | Example Values | -|-------|------|-----------|---------|----------------| -| `locale` | String | OPTIONAL | Locale for dateparser/recurrent | `en_US`, `fr_FR`, `de_DE` | -| `timezone` | String | OPTIONAL | Default timezone for datetime fields | `America/New_York`, `Europe/Paris`, `UTC` | +| Field | Type | Purpose | +|-------|------|---------| +| `locale` | String | Locale for dateparser/recurrent (`en_US`, `fr_FR`) | +| `timezone` | String | Default timezone (`America/New_York`, `UTC`) | +| `date_format` | String | Output date format (`%Y-%m-%d`, `%d/%m/%Y`) | -**Processing Order:** - -1. Parse YAML front matter (if present) -2. Extract `locale` and `timezone` values -3. Apply to all subsequent date/time parsing +**See [spec/frontmatter.md](spec/frontmatter.md) for detailed field behavior, processing order, and file scope rules.** --- @@ -421,88 +418,32 @@ ## Backend Operations +Backend #critical -- [ ] (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 +- [ ] (A) 2024-03-10 Fix database connection @alice +Database due:2024-03-15T18:00 ~8h type:urgent - [ ] (B) 2024-03-10 Update connection pooling @alice ~2h - - [ ] (B) 2024-03-11 Add retry logic @bob ~3h - [x] (C) 2024-03-09 2024-03-10 Write migration @alice ~3h -- [ ] 2024-03-15T09:00 Daily status report @alice repeat:"weekdays at 9am" due:2024-03-15T09:30 ~30m type:report +- [ ] 2024-03-15T09:00 Daily status report @alice repeat:"weekdays at 9am" ~30m ``` **After Inheritance:** - First task: `+Acme/Backend/Database`, `#work`, `#critical` - Subtasks: Inherit parent + section + top-level metadata -- Daily report: `+Acme/Backend`, `#work`, `#critical` - -### 10.3 Date and Time Examples - -```markdown -# TODO +MyProject - -## Date-only -- [ ] (A) 2024-03-10 Start project planning -- [x] (B) 2024-03-01 2024-03-05 Complete requirements - -## Time-specific -- [ ] 2024-03-15T09:00 Morning standup due:2024-03-15T09:30 -- [ ] 2024-03-15T14:00 Client presentation due:2024-03-15T15:00 - -## With timezones -- [ ] 2024-03-15T09:00-05:00 Team call (EST) -- [ ] 2024-03-15T15:00+01:00 European meeting -## Full lifecycle -- [ ] (A) 2024-03-10T09:00 Implement OAuth2 @alice created:2024-03-01T10:00 started:2024-03-10T09:00 due:2024-03-15T18:00 - -## Recurring -- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am" -- [ ] 2024-04-01 Monthly review repeat:"first day of month" -``` - -**Result:** All tasks inherit `+MyProject` from top-level section. - -### 10.4 YAML Front Matter - -```markdown ---- -locale: en_US -timezone: America/New_York ---- - -# TODO - -## Meetings -- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am" -- [ ] 2024-04-01 Monthly review repeat:"first day of month" - -## Tasks -- [ ] (A) 2024-03-10 Start development @alice due:2024-03-15T17:00 -``` - -**Result:** All datetimes without explicit timezone use `America/New_York` (EST/EDT). +**See [spec/examples.md](spec/examples.md) for date/time examples, YAML front matter examples, and multi-file examples.** --- ## 11. Library Stack -### 11.1 Required Libraries - -| Purpose | Library | Version | Usage | -|---------|---------|---------|-------| -| Natural language → datetime | [dateparser](https://dateparser.readthedocs.io/) | Latest | Parse phrases like "next Friday 3pm" | -| Natural language → recurrence | [recurrent](https://github.com/kvh/recurrent) | Latest | Parse "every Tuesday" into RRULE | -| Recurrence → dates | [python-dateutil](https://dateutil.readthedocs.io/) | Latest | Generate occurrence dates from RRULE | -| Datetime wrapper | [pendulum](https://pendulum.eustace.io/) | Latest | Timezone-aware datetime operations | +| Purpose | Library | Usage | +|---------|---------|-------| +| Natural language → datetime | [dateparser](https://dateparser.readthedocs.io/) | Parse "next Friday 3pm" | +| Natural language → recurrence | [recurrent](https://github.com/kvh/recurrent) | Parse "every Tuesday" into RRULE | +| Recurrence → dates | [python-dateutil](https://dateutil.readthedocs.io/) | Generate occurrence dates | +| Datetime wrapper | [pendulum](https://pendulum.eustace.io/) | Timezone-aware operations | -### 11.2 Processing Pipeline - -| Step | Input | Library | Output | -|------|-------|---------|--------| -| 1 | Natural language date | dateparser | Datetime object | -| 2 | Natural language recurrence | recurrent | RRULE string | -| 3 | RRULE string | python-dateutil | List of datetime objects | -| 4 | Datetime object | pendulum | Timezone-aware datetime | +**See [spec/libraries.md](spec/libraries.md) for detailed library usage and processing pipeline.** --- @@ -552,36 +493,15 @@ timezone: America/New_York ## 14. Format Compatibility -### 14.1 todo.txt Conversion - -| Element | todo.txt | TaskMark | Conversion Rule | -|---------|----------|---------|----------------| -| Priority | `(A)` at start | `(A)` after state | Move after `- [ ]` | -| Contexts | `@context` | `#context` | Replace `@` with `#` | -| Projects | `+project` | `+project` | No change | -| Assignees | Not supported | `@user` | Add if needed | -| Dates | Creation date required | Optional | Remove if unwanted | -| Sections | Not supported | `## Section` | Group by project | - -### 14.2 todo.md Conversion - -| Element | todo.md | TaskMark | Conversion Rule | -|---------|---------|---------|----------------| -| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed | -| Priority | Not standardized | `(value)` after state | Add if needed | -| Metadata | Freeform | `key:value` | Standardize format | -| Recurrence | Not supported | `repeat:PATTERN` | Add if needed | -| File links | Not supported | `[text](file.md)` | Add if needed | - -### 14.3 xit Conversion - -| Element | xit | TaskMark | Conversion Rule | -|---------|-----|---------|----------------| -| Date headers | `2024-03-15` | `## Section` | Convert to sections | -| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed | -| Metadata | `key:value` | `key:value` | Extract core fields | -| Priority | Not supported | `(value)` | Add if needed | -| Projects | `project:name` | `+name` | Convert syntax | +TaskMark supports conversion to/from other task formats: + +| Format | Full Compatibility | Notes | +|--------|-------------------|-------| +| todo.txt | → TaskMark: Yes | Contexts become tags | +| todo.md | → TaskMark: Yes | Add priority, metadata | +| xit | → TaskMark: Yes | Date headers become sections | + +**See [spec/compatibility.md](spec/compatibility.md) for detailed conversion rules and examples.** ---