m038/intotheeast-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
203737cc3fc349aefbbde066b25842000ee1c061
intotheeast-com/docs/working/specs/2026-06-20-pixelfed-import-design.md
T

5.5 KiB
Raw Blame History

Pixelfed Import & Demo Reorganisation — Design Spec

Date: 2026-06-20 Status: Approved

Overview

Import 36 Pixelfed posts from gram.social/m038 (exported as pixelfed-statuses.json) into three new permanent trips. Simultaneously reorganise the demo system: move the Italy demo trip to a clearly-labelled 2026 demo slug and retire the Japan demo entries.

Scope

What this covers

  1. Demo system reorganisation (Italy 2025 demo → italy-2026-demo, Japan demo retired)
  2. Three new real trip page trees
  3. A one-time Python import script that routes posts to the correct trip, downloads photos, and writes Grav entry folders
  4. Updated Makefile demo-load / demo-reset targets

What this does not cover

  • Generating proper titles (done interactively with Claude after import)
  • Adding GPX routes to real trips
  • Lat/lng geocoding (location data from the export has city/country only, no coordinates)

Part 1: Demo System Reorganisation

1a. Italy demo moves to italy-2026-demo

Copy user/docs/demo/trips/italy-2025/ → user/docs/demo/trips/italy-2026-demo/.

Update the trip page frontmatter inside the new demo source:

title: 'Italy 2026 (Demo)'
slug: italy-2026-demo

Create the real page tree at user/pages/01.trips/italy-2026-demo/ with the standard four subfolders.

Update Makefile:

  • demo-load: replace all italy-2025 references with italy-2026-demo
  • demo-reset: replace rm -rf user/pages/01.trips/italy-2025 with rm -rf user/pages/01.trips/italy-2026-demo

italy-2025 is never touched by demo commands after this change.

1b. Japan demo retired

Remove all japan-korea-2026 blocks from demo-load and demo-reset.

The source files in user/docs/demo/trips/japan-korea-2026/ stay on disk as a backup but are not loaded by any make target. The japan-korea-2026 trip structure and any real content committed there remains untouched.

1c. Italy 2025 demo stories removed

The 3 Tuscany demo stories currently at user/pages/01.trips/italy-2025/04.stories/ (if present on disk) are deleted — they are moving to the demo trip. The 04.stories/ folder itself is kept with its stories.md index page.

Part 2: Real Trip Page Trees

Three trips get the standard structure: trip.md, 01.dailies/dailies.md, 02.map/map.md, 03.stats/stats.md, 04.stories/stories.md.

Slug Title Action
central-asia-2023 Central Asia 2023 Create new
us-canada-mex-2024 Northern America 2024 Create new
italy-2025 Cycling Tuscany 2025 Exists — update title only

All three are committed to the user/ git repo as permanent content.

Part 3: Pixelfed Import Script

Location

scripts/pixelfed-import.py

Invoked via: make pixelfed-import

Input

/home/mischa/Nextcloud/Downloads/pixelfed/pixelfed-statuses.json (36 posts, Pixelfed v1 export format)

Trip routing by year

created_at year Target trip
2023 central-asia-2023
2024 us-canada-mex-2024
2025 italy-2025

Posts are numbered per trip (1-indexed), reset for each trip.

Output folder structure

For each post, one folder inside user/pages/01.trips/{trip}/01.dailies/:

{YYYY-MM-DD}-pixelfed-{N}.entry/
    entry.md
    photo-1.jpg
    photo-2.jpg
    ...

Where N is the per-trip sequence number and YYYY-MM-DD comes from created_at.

Field mapping

Pixelfed field Grav frontmatter field Notes
created_at date ISO 8601 → Y-m-d H:i
(generated) title "Pixelfed Import {N}"
place.name location_city Empty string if place is null
place.country location_country Empty string if place is null
(none) lat, lng Always empty — no coordinate data in export
(none) weather_temp_c, weather_desc Always empty
first downloaded photo filename hero_image e.g. photo-1.jpg
content_text body Already HTML-stripped in export

Fixed frontmatter values: template: entry, published: true.

Photo download

For each item in media_attachments:

  • Download from url field
  • Save as photo-{index}.jpg (1-indexed) regardless of original filename
  • Use the extension from the mime field (image/png → .png, image/jpeg → .jpg)
  • Set hero_image in frontmatter to the filename of the first downloaded photo

Error handling

  • If a photo download fails, log a warning and continue (do not abort the post)
  • If the output folder already exists, skip that post (idempotent re-runs)

Make target

pixelfed-import:
	python3 scripts/pixelfed-import.py

File Map

File Change
user/docs/demo/trips/italy-2026-demo/ New — copy of italy-2025 demo source with updated title/slug
user/pages/01.trips/italy-2026-demo/ New — demo trip page tree
user/pages/01.trips/italy-2025/trip.md Update title to "Cycling Tuscany 2025"
user/pages/01.trips/italy-2025/04.stories/ Remove 3 demo story subfolders
user/pages/01.trips/central-asia-2023/ New — real trip page tree
user/pages/01.trips/us-canada-mex-2024/ New — real trip page tree
Makefile Update demo-load / demo-reset targets
scripts/pixelfed-import.py New — one-time import script

Constraints

  • Never read .env directly
  • All CSS uses design tokens — script produces no CSS
  • Import script writes to user/pages/ only; caller runs make content-push afterwards to commit and sync
  • The italy-2025 trip must never appear in demo-load or demo-reset after this change
Reference in New Issue View Git Blame Copy Permalink