Skip to main content

Rambles Section — Design Spec

Date: 2026-04-06
Status: Approved

Context​

The site currently has Portfolio, Tutorials, Shop, and Revision sections, all built as Docusaurus plugin-content-docs instances. The user wants a new Rambles section for walking and place reviews, organised by geography (Country → County → City → Place). 200 existing Google Maps reviews will be imported as the initial content via a one-off Python script.

Architecture​

Section wiring (same pattern as Portfolio)​

New files:

  • sidebarsRambles.js — autogenerated sidebar, mirrors sidebarsPortfolio.js
  • rambles/index.md — hand-crafted landing page (intro text + links to regions)

Changes to existing files:

  • docusaurus.config.js — add plugin entry and navbar item
  • Plugin entry: 
    {
      id: 'rambles',
      path: 'rambles',
      routeBasePath: 'rambles',
      sidebarPath: './sidebarsRambles.js',
    }
  • Navbar item added after Portfolio: 
    { type: 'doc', docId: 'index', docsPluginId: 'rambles', label: 'Rambles' }

Folder Structure​

rambles/
├── index.md                              ← Hand-crafted landing page
└── united-kingdom/
    ├── _category_.json                   ← Auto-lists counties
    └── cheshire/
        ├── _category_.json               ← Auto-lists cities
        └── macclesfield/
            ├── _category_.json           ← Auto-lists places + grouping articles
            ├── top-10-museums.md         ← Manually written city grouping article
            └── prestbury-park/
                └── index.md             ← Individual place review

Container folders use _category_.json (no index.md needed)​

{
  "label": "Macclesfield",
  "link": {
    "type": "generated-index",
    "description": "Walking and place reviews around Macclesfield"
  }
}

Docusaurus auto-generates a card-grid listing page — no manual link maintenance required at any hierarchy level.

Individual place reviews​

Each place lives in its own folder with an index.md. No date in frontmatter (reviews should feel timeless).

---
title: "Prestbury Park"
rating: 3
google_maps_url: "https://www.google.com/maps/place/..."
address: "41 Bollin Grove, Prestbury, Macclesfield SK10 4JJ, United Kingdom"
latitude: 53.2944502
longitude: -2.1531036
---

**Rating:** ⭐⭐⭐ (3/5)  
**Address:** 41 Bollin Grove, Prestbury, Macclesfield SK10 4JJ, United Kingdom  
**Coordinates:** 53.2944502, -2.1531036  
**[View on Google Maps](https://...)**

---

The row of hornbeam trees...

Google Maps Import Script​

Location: scripts/import-google-reviews.py
Source data: /home/andrew/Documents/takeout/1/Takeout/Maps (your places)/Reviews.json
Output: rambles/ folder tree
Run: once, then discarded

Algorithm​

For each of the 200 reviews in the JSON (features array):

  1. Extract fields: location.name, review_text_published, five_star_rating_published, google_maps_url, location.address, geometry.coordinates (GeoJSON order: [longitude, latitude])
  2. Skip reviews with an empty location.name (3 exist in the dataset)
  3. Extract UK postcode from address using regex [A-Z]{1,2}\d{1,2}[A-Z]?\s?\d[A-Z]{2}
  4. Map postcode area prefix (e.g. SK, M, TA) → county slug using built-in lookup table
  5. Parse city from address: the named segment immediately before the postcode (e.g. "..., Macclesfield SK10 4JJ, ..." → macclesfield)
  6. Slugify place name (lowercase, non-alphanumeric → -, strip leading/trailing -)
  7. Handle duplicate slugs within the same city folder by appending -2, -3 etc.
  8. Create directory rambles/united-kingdom/{county}/{city}/{place-slug}/
  9. Create _category_.json in each intermediate folder if one doesn't already exist
  10. Write index.md with frontmatter + rendered body (rating stars, address, Google Maps link, review text)
  11. Reviews with no postcode → placed in rambles/united-kingdom/uncategorised/{place-slug}/

Known edge cases (14 reviews, handled automatically)​

PlaceIssueHandling
Burnham-on-sea Low LighthouseNo postcode→ uncategorised/
Derbyshire Bridge Car ParkNo postcode→ uncategorised/
Westward Ho! BeachNo postcode→ uncategorised/
Knight's Pool, Saddler's Wy, Maggoty Wood"Macclesfield, UK" only→ uncategorised/
Henbury Millennium GreenPartial postcode SK11→ parsed normally
3 empty-name reviewsNo name→ skipped

After the script runs, the user moves any uncategorised/ items to their correct folders manually.

Postcode area → county mapping (partial)​

PrefixCounty slug
SKcheshire
Mgreater-manchester
TAsomerset
OL, BL, WNgreater-manchester
CHcheshire
CWcheshire
DEderbyshire
NGnottinghamshire
SAwales
LD, CF, NPwales
(others)derived from prefix or uncategorised

Note: SK covers both Cheshire East (SK8–SK12) and Stockport/Greater Manchester (SK1–SK7). The script maps all SK → cheshire for simplicity; Stockport-area reviews can be moved manually if needed.

Verification​

  1. Run python3 scripts/import-google-reviews.py — check terminal summary for skipped/uncategorised count
  2. cd to rambles/ and verify folder tree looks correct for a few known places
  3. Run npm start — confirm Rambles appears in navbar
  4. Navigate to /rambles/united-kingdom/cheshire/macclesfield/ — confirm auto-generated card grid shows place reviews
  5. Open one place review — confirm rating stars, address, coordinates, Google Maps link, and review text all render correctly
  6. Check rambles/united-kingdom/uncategorised/ — manually re-home any reviews there
Adverts