From 6d43c65dc673b2b96ffbed76d7c477964a1cb6ed Mon Sep 17 00:00:00 2001 From: Mischa Date: Sun, 21 Jun 2026 12:55:31 +0200 Subject: [PATCH] docs: rewrite posting guide as user-facing step-by-step --- docs/guides/posting.md | 173 +++++++++++++++++++---------------------- 1 file changed, 78 insertions(+), 95 deletions(-) diff --git a/docs/guides/posting.md b/docs/guides/posting.md index 3011af5..5e232f9 100644 --- a/docs/guides/posting.md +++ b/docs/guides/posting.md @@ -1,132 +1,115 @@ -# Daily Entry Posting Pipeline +# Posting a Journal Entry -Two ways to create a daily entry: the mobile frontend form at `/post`, or directly from the Grav Admin2 panel. Both produce the same page structure under `user/pages/01.trips//01.dailies/`. - -The active trip is set in `user/config/site.yaml` → `active_trip`. The post form's `pageconfig.parent` in `post-form.md` must be kept in sync with this value. +Two ways to post: the **mobile form** at `/post` (quick, phone-friendly) or the **Admin panel** at `/admin` (drafts, scheduling, editing). --- -## Frontmatter Reference +## Quick start — mobile form -Every entry page (`template: entry`) supports these frontmatter fields: +1. Open `/post` on your phone (login required) +2. Fill in **Title** and **Content** (required) +3. Tap **Get Location** → fills Lat/Lng automatically +4. Tap **Get Weather** → fills weather fields using your coordinates +5. Type **City** and **Country** (optional but nice) +6. Attach photos (optional) — first photo becomes the hero image +7. Tap **Submit** → entry appears in the feed immediately -| Field | Type | Required | Notes | -|---|---|---|---| -| `title` | string | ✅ | Entry headline | -| `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 tracker feed | -| `lat` | string | — | Latitude decimal degrees (e.g. `52.3676`) | -| `lng` | string | — | Longitude decimal degrees (e.g. `4.9041`) | -| `location_city` | string | — | City name shown under the title (e.g. `Kyoto`) | -| `location_country` | string | — | Country name shown under the title (e.g. `Japan`) | -| `weather_desc` | string | — | Condition label — must be one of the values below | -| `weather_temp_c` | number | — | Temperature in Celsius (displayed rounded, e.g. `19`) | -| `hero_image` | string | — | Filename of the hero image (e.g. `photo.jpg`). Leave blank to auto-select the first uploaded image. | +--- -**`weather_desc` allowed values** (matched to emoji icons in `entry.html.twig`): +## Form fields reference + +| Field | Required | Notes | +|---|---|---| +| Title | ✅ | Entry headline | +| Content | ✅ | Markdown body | +| Date | ✅ | Defaults to now — adjust if posting later | +| Lat / Lng | — | Filled by Get Location; used for map marker | +| City | — | Shown as `📍 Kyoto, Japan` on feed cards | +| Country | — | Combined with City in location badge | +| Weather | — | Filled by Get Weather (Open-Meteo, free, no key) | +| Photos | — | All uploaded files appear in the gallery; first = hero | + +**Weather descriptions** (must be one of these if entered manually): `Sunny` · `Partly cloudy` · `Cloudy` · `Foggy` · `Drizzle` · `Rain` · `Snow` · `Thunderstorm` -**Page media (photos):** images are stored as files in the page folder (`user/pages/01.tracker//`). All images in the folder are shown in the gallery. `hero_image` pins one as the full-width header. - -**Example complete frontmatter:** -```yaml ---- -title: 'First Day in Kyoto' -date: '2026-07-20 09:30' -template: entry -published: true -lat: '35.0116' -lng: '135.7681' -location_city: 'Kyoto' -location_country: 'Japan' -weather_desc: 'Sunny' -weather_temp_c: 28 -hero_image: 'temple.jpg' ---- -``` - --- -## Flow 1 — Mobile Frontend Form (`/post`) - -This is the primary posting flow, designed for one-handed phone use. +## How it works (for debugging) ``` Browser → /post (post-form.md) └─ Grav Form plugin validates fields - └─ add-page-by-form plugin (onFormProcessed) - ├─ reads pageconfig.parent (/trips/japan-korea-2026/dailies) and pageconfig.slug_field (date + title) - ├─ reads pagefrontmatter (template: entry, published: true) - ├─ merges form field values into new page frontmatter + └─ add-page-by-form plugin + ├─ reads pageconfig.parent (/trips//dailies) ├─ writes user/pages/01.trips//01.dailies//entry.md └─ moves uploaded photos into the page folder - └─ cache-on-save plugin (onFormProcessed) - └─ calls $grav['cache']->deleteAll() so tracker feed shows the entry immediately - └─ form shows success message, resets fields + └─ cache-on-save plugin + └─ calls $grav['cache']->deleteAll() → entry visible immediately + └─ form shows success message ``` -**The form fields and their mapping to frontmatter:** +**Slug format:** `-.entry` +Example: `2026-07-20-0930-first-day-in-kyoto.entry` -| Form field | Frontmatter key | Notes | -|---|---|---| -| `title` | `title` | Required | -| `date` | `date` | Defaults to current datetime | -| `content` | page body (markdown) | Required | -| `photos` | page media files | Uploaded to page folder | -| `lat` | `lat` | Filled via "Get Location" button | -| `lng` | `lng` | Filled via "Get Location" button | -| `location_city` | `location_city` | Manual text entry | -| `location_country` | `location_country` | Manual text entry | -| `weather_temp_c` | `weather_temp_c` | Hidden — set by weather JS widget | -| `weather_desc` | `weather_desc` | Hidden — set by weather JS widget | - -**Slug format:** `.` (controlled by `slug_field: 'date,title'` in `post-form.md`). - -**Security:** the `/post` page requires `access: site.login: true` — anonymous visitors get redirected to login. +**Entry folder structure:** +``` +user/pages/01.trips/japan-korea-2026/01.dailies/ +└─ 2026-07-20-0930-first-day-in-kyoto.entry/ + ├─ entry.md ← frontmatter + markdown body + ├─ temple.jpg ← hero image (or set hero_image in frontmatter) + └─ market.jpg ← additional gallery image +``` --- -## Flow 2 — Admin Panel (sit-down workflow) +## Admin panel — drafts and scheduling -Use this for drafts, scheduled posts, or editing existing entries. +Use the Admin panel at `/admin` for drafts, scheduled posts, or editing existing entries. 1. Log in at `/admin` -2. Go to **Pages** → **Add Page** -3. Set: - - **Page Title:** your entry title - - **Parent Page:** `/trips/japan-korea-2026/dailies` (adjust to active trip) - - **Page Template:** `entry` -4. Fill in the **Entry** tab fields (city, country, lat/lng, weather) +2. **Pages → Add Page** +3. Set **Parent Page** to `/trips//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 via the **Media** tab -7. Set `published: true` (or leave `false` for a draft) -8. For scheduling: set `publish_date` in **Options** → **Scheduling** +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`. -**Drafts:** set `published: false` — the entry won't appear in the tracker feed until you flip it to `true`. Useful for writing ahead of time on the road. +--- -**Scheduling:** Grav supports `publish_date` and `unpublish_date` in page frontmatter. Set them in the Admin Options tab. Requires `pages.publish_dates: true` in `system.yaml` (already enabled). +## 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 | +| `hero_image` | string | Filename to pin as hero (e.g. `temple.jpg`); auto-selects first image if blank | --- -## Page folder structure +## Troubleshooting -``` -user/pages/01.trips/ -└─ japan-korea-2026/ ← trip entity (active_trip in site.yaml) - ├─ trip.md ← trip page (title, date_start, date_end, cover_image, album_url) - ├─ *.gpx ← GPX route files (served as media, rendered on map) - ├─ 01.dailies/ - │ └─ 2026-07-20-1430-first-day-in-kyoto.entry/ - │ ├─ entry.md ← frontmatter + markdown body - │ ├─ temple.jpg ← hero image (referenced by hero_image) - │ └─ market.jpg ← additional gallery image - ├─ 02.map/map.md - ├─ 03.stats/stats.md - └─ 04.stories/stories.md -``` +**Entry doesn't appear in feed after submit** +→ Check that `active_trip` in `user/config/site.yaml` matches the parent in `user/pages/02.post/post-form.md` (`pageconfig.parent`). If they're out of sync, entries go to the wrong folder. See [trip switching guide](trip-switching.md). -The entry folder name follows `-.entry`. Grav uses this for ordering and routing. The `.entry` suffix enables the `entry` template. +**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. + +**500 error after posting** +→ Run `make fix-perms` to restore container file ownership.