Decision: confirm typed `!!field:type!!` syntax + `## App Config` convention

cloudbot commented

2026-07-23 14:46:22 +02:00

Collaborator

Decision #2 — confirm the typed !!field:type!! syntax and the ## App Config convention before the template parser is built.

Templates are authored with Outline's native Template feature, and the app parses each template's markdown body. Outline already uses !!placeholder!! for free-text prompts (no type info). The proposal extends that convention with a field: prefix so the app can render the right input control while the template stays human-readable (and harmless) if opened directly in Outline.

Proposed field syntax: `!!field:<type>[:<options>]!!`

Type	Syntax	Renders as
One-line string	`!!field:string!!`	Text field
Multiline	`!!field:multiline!!`	Text area
Checkbox	`!!field:checkbox!!`	Toggle
Dropdown	`!!field:dropdown:A,B,C!!`	Dropdown
Number	`!!field:number!!`	Numeric input
Time	`!!field:time!!`	Time picker
Date	`!!field:date!!`	Date picker

(Expanded set — photo, checklist, showIf — is tracked separately in #6.)

Proposed `## App Config` block

A table at the very top of the template body, parsed before the field placeholders, controlling routing/targeting:

## App Config
| Key | Value |
|---|---|
| entry_id | dentist_appointment |
| button_label | Log Dentist Appointment |
| icon | 🦷 |
| applies_to | family_member |
| target_mode | append |
| target_doc | {{family_member.documentId}} |
| position | bottom |
| heading_level | 2 |

What to decide

Confirm !!field:type!! as the field syntax.
Confirm the ## App Config key set (names + meaning) and that it lives as the first table in the template.
Confirm the key acceptance criterion: a template with these annotations still reads sensibly and does no harm when opened directly in Outline (placeholders render as literal text, App Config reads as a normal table).
Confirm the Log-button icon comes from the App Config icon key (an emoji, e.g. 🦷) — not the template's native Outline doc icon. The doc icon can be a custom uploaded image (stored as a UUID needing a separate resolution path — see #9), and most existing templates set no icon at all, so App Config is the reliable, self-contained source.

Blocks: the template parser.

Recommendation: adopt both as proposed. The field: prefix is a clean superset of Outline's existing !!...!! and degrades to visible placeholder text in Outline; the ## App Config table is likewise just a normal table to a human reader. Suggest reserving one worked template (Dentist Appointment) as the reference implementation once approved.

Source: Solution Design — Family App v1 §5 (doc vpBNbG4TsV), decision §13 #2.

**Decision #2 — confirm the typed `!!field:type!!` syntax and the `## App Config` convention before the template parser is built.** Templates are authored with **Outline's native Template feature**, and the app parses each template's markdown body. Outline already uses `!!placeholder!!` for free-text prompts (no type info). The proposal extends that convention with a `field:` prefix so the app can render the right input control while the template stays human-readable (and harmless) if opened directly in Outline. ### Proposed field syntax: `!!field:<type>[:<options>]!!` | Type | Syntax | Renders as | |------|--------|------------| | One-line string | `!!field:string!!` | Text field | | Multiline | `!!field:multiline!!` | Text area | | Checkbox | `!!field:checkbox!!` | Toggle | | Dropdown | `!!field:dropdown:A,B,C!!` | Dropdown | | Number | `!!field:number!!` | Numeric input | | Time | `!!field:time!!` | Time picker | | Date | `!!field:date!!` | Date picker | (Expanded set — `photo`, `checklist`, `showIf` — is tracked separately in #6.) ### Proposed `## App Config` block A table at the very top of the template body, parsed before the field placeholders, controlling routing/targeting: ``` ## App Config | Key | Value | |---|---| | entry_id | dentist_appointment | | button_label | Log Dentist Appointment | | icon | 🦷 | | applies_to | family_member | | target_mode | append | | target_doc | {{family_member.documentId}} | | position | bottom | | heading_level | 2 | ``` ### What to decide 1. Confirm `!!field:type!!` as the field syntax. 2. Confirm the `## App Config` key set (names + meaning) and that it lives as the first table in the template. 3. Confirm the key acceptance criterion: **a template with these annotations still reads sensibly and does no harm when opened directly in Outline** (placeholders render as literal text, App Config reads as a normal table). 4. Confirm the **Log-button icon comes from the App Config `icon` key** (an emoji, e.g. `🦷`) — **not** the template's native Outline doc icon. The doc icon can be a custom uploaded image (stored as a UUID needing a separate resolution path — see #9), and most existing templates set no icon at all, so App Config is the reliable, self-contained source. **Blocks:** the template parser. **Recommendation:** adopt both as proposed. The `field:` prefix is a clean superset of Outline's existing `!!...!!` and degrades to visible placeholder text in Outline; the `## App Config` table is likewise just a normal table to a human reader. Suggest reserving one worked template (Dentist Appointment) as the reference implementation once approved. **Source:** Solution Design — Family App v1 §5 ([doc vpBNbG4TsV](https://outline.marquezkeenan.family/doc/solution-design-family-app-v1-vpBNbG4TsV)), decision §13 #2.

cloudbot added this to the M0 · Open Questions & Decisions milestone

2026-07-23 14:46:22 +02:00

cloudbot added the

spike

label

2026-07-23 14:46:22 +02:00

cloudbot added a new dependency

2026-07-23 14:46:42 +02:00

#24 Template fetch + parser

cloudbot referenced this issue

2026-07-23 17:37:18 +02:00

Decision: expanded field set (photo, checklist) + showIf #6