intotheeast-com/docs/guides/posting.md

# Posting a Journal Entry

Two ways to post: the **mobile form** at `/post` (quick, phone-friendly) or the **Admin panel** at `/admin` (scheduling, bulk edits). The `/post` form also **edits** existing entries — see below.

---

## Quick start — mobile form

1. Open `/post` on your phone (login required)
2. **Attach 1–6 photos** — photos come first because they anchor what you write. **At least one is required**; the form collapses them into a summary bar once uploaded
3. Fill in **Title** and **Content** (required)
4. Tap **Get Location** → fills Lat/Lng, then reverse-geocodes City + Country for you
5. Tap **Get Weather** → fills weather fields using those coordinates
6. Optional: open **More location details** to search for a place by name, or drag the pin on the map to place it exactly
7. Optional: open **More options** for transport mode, publish state, connector and highlight toggles
8. Tap **Submit** → entry appears in the feed immediately

> **Photos are mandatory (1–6).** This changed during the 2026-07 post-form work — an entry with no
> photo will not submit. The first photo in the grid is the hero; reorder by dragging to change it.
> See [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md) → R7, R8.

---

## Form fields reference

| Field | Required | Notes |
|---|---|---|
| Photos | ✅ | **1–6 per entry.** HEIC is converted to JPEG in the browser. First photo = hero; drag to reorder |
| Title | ✅ | Entry headline |
| Content | ✅ | Markdown body |
| Date | ✅ | Defaults to now — adjust if posting later |
| Lat / Lng | — | Filled by Get Location, by place search, or by dragging the map pin |
| City | — | Auto-filled by reverse geocoding after Get Location; shown as `📍 Kyoto, Japan` on feed cards |
| Country | — | Combined with City in the location badge |
| Weather | — | Filled by Get Weather (Open-Meteo, free, no key) |
| How I got here | — | `transport_mode`: walking · bicycle · bus · train · car · plane |
| Published | — | Advanced. Default **Yes**. Set No to keep a draft, or to unpublish on edit |
| Force connector line | — | Advanced. Default No. Forces a map connector to this entry even when suppressed |
| Featured highlight | — | Advanced. Default No. Opts the entry into the home highlights grid |

The advanced three sit behind **More options**. There is **no `hero_image` field** — see the note above.

**Weather descriptions** (must be one of these if entered manually):
`Sunny` · `Partly cloudy` · `Cloudy` · `Foggy` · `Drizzle` · `Rain` · `Snow` · `Thunderstorm`

---

## How it works (for debugging)

```
Browser → /post (post-form.md)
         └─ Grav Form plugin validates fields
         └─ cache-on-save injects parent from site.active_trip
              └─ and sets overwrite_mode: edit when edit_path is filled, else false
         └─ add-page-by-form plugin (patched — see deploy/patches/)
              ├─ writes user/pages/01.trips/<active_trip>/01.dailies/<slug>.entry/entry.md
              └─ moves uploaded photos into the page folder
         └─ cache-on-save plugin
              └─ calls $grav['cache']->deleteAll() → entry visible immediately
         └─ form shows success message
```

**Slug format:** `<YYYY-MM-DD-HHmm>-<slugified-title>.entry`
Example: `2026-07-20-0930-first-day-in-kyoto.entry`

**Entry folder structure:**
```
user/pages/01.trips/denmark-2026/01.dailies/
└─ 2026-07-20-0930-first-day-in-kyoto.entry/
   ├─ entry.md        ← frontmatter + markdown body
   ├─ photo-01.jpg    ← first in order, so this is the hero
   └─ photo-02.jpg    ← additional gallery image
```

Photos are stored as `photo-01…NN` in display order — the numbering *is* the order, so reordering in
the form renames files on disk, and `photo-01` is always the hero. Names are **zero-padded** so
lexical sort matches numeric order (otherwise `photo-1, photo-10, photo-2…`); the pad width grows for
100+ photos. `PhotoRenumberer` in `cache-on-save` is the single source of truth for this invariant and
is shared with `entry-actions`.

---

## Admin panel — drafts and scheduling

Use the Admin panel at `/admin` for **scheduling** (`publish_date`) and bulk or structural edits. For ordinary edits — text, photos, location, publish state — the `/post` form is quicker; see [Editing an entry](#editing-an-entry).

1. Log in at `/admin`
2. **Pages → Add Page**
3. Set **Parent Page** to `/trips/<active_trip>/dailies` and **Template** to `entry`
4. Fill in the **Entry** tab (city, country, lat/lng, weather)
5. Write content in the **Content** tab
6. Upload photos in the **Media** tab
7. **Drafts:** set `published: false` — won't appear until you flip it to `true`
8. **Scheduling:** set `publish_date` in **Options → Scheduling**
9. Save

The Admin form fields are defined by `user/themes/intotheeast/blueprints/entry.yaml`.

---

## Frontmatter reference

Every entry supports these frontmatter fields:

| Field | Type | Notes |
|---|---|---|
| `title` | string | Required |
| `date` | datetime | Format: `Y-m-d H:i` (e.g. `2026-06-17 10:00`) |
| `template` | string | Always `entry` |
| `published` | bool | `true` to show in feed |
| `lat` | string | Decimal degrees (e.g. `52.3676`) |
| `lng` | string | Decimal degrees (e.g. `4.9041`) |
| `location_city` | string | e.g. `Kyoto` |
| `location_country` | string | e.g. `Japan` |
| `weather_desc` | string | One of the allowed values above |
| `weather_temp_c` | number | Celsius, displayed rounded |
| `transport_mode` | string | `walking` · `bicycle` · `bus` · `train` · `car` · `plane` |
| `force_connect` | bool | Force a map connector line to this entry even where it would be suppressed |
| `featured` | bool | Opt into the home page highlights grid |

> **No `hero_image` on journal entries.** The hero is whichever photo sorts first
> (`entry-journal.html.twig` uses `entry.media.images|first`), which the owner controls by
> reordering photos. **Stories still use `hero_image`** — they are not posted through this form.
> See [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md) → R7.

---

## Editing an entry

The `/post` form doubles as the editor — you do not need Admin for ordinary edits.

1. Open the entry (or find it in the feed) while logged in
2. Use the entry's **Edit** action → `/post` opens pre-filled, with the hidden `edit_path` set to that
   entry's path
3. Existing photos load into the grid. You can **add**, **remove**, and **drag to reorder** them
4. Submit → `cache-on-save` sets `overwrite_mode: edit`, so the entry is rewritten **in place**
   rather than creating a new dated folder

Photo files on disk are renumbered to `photo-1…N` to match the displayed order, so the first photo is
always the hero. Reordering is a real file rename, handled server-side by `PhotoRenumberer` in the
`entry-actions` plugin via `POST /api/v1/entry/{slug}/photos/order`.

To **unpublish** an entry, edit it and set **Published** to No under *More options*.

Deleting an entry is also an entry action (`DELETE /api/v1/entry/{slug}`), owner-only and scoped to
the active trip.

---

## Troubleshooting

**Entry doesn't appear in feed after submit**
→ Check `active_trip` in `user/config/site.yaml` — the write target is derived from it at submit time, so a wrong value sends entries to the wrong trip's dailies. See [trip switching guide](trip-switching.md).

**Get Weather button shows an error**
→ Fill in Lat/Lng first (tap Get Location or enter manually). Open-Meteo requires coordinates.

**Photos not showing in gallery**
→ Verify files were uploaded (check the entry folder in Admin → Media). Only jpg, jpeg, png, webp, gif are rendered.

**Submit button does nothing**
→ Check you have at least one photo attached, and that every upload has finished. The form blocks
submit while an upload is still in flight, and requires 1–6 photos.

**500 error after posting**
→ Run `make fix-perms` to restore container file ownership.

**Edits create a new entry instead of updating**
→ The hidden `edit_path` was empty, so `overwrite_mode` fell back to `false`. Re-enter via the entry's
Edit action rather than opening `/post` directly.