docs: rewrite posting guide as user-facing step-by-step
This commit is contained in:
+78
-95
@@ -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/<active_trip>/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/<slug>/`). 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/<active_trip>/dailies)
|
||||
├─ writes user/pages/01.trips/<active_trip>/01.dailies/<slug>/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:** `<YYYY-MM-DD-HHmm>-<slugified-title>.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:** `<YYYY-MM-DD>.<slugified-title>` (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/<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 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 `<YYYY-MM-DD-HHmm>-<slug>.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.
|
||||
|
||||
Reference in New Issue
Block a user