stumbo · Nov 11, 2026 · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026 · masinter
diff --git a/README.md b/README.md
@@ -19,6 +19,9 @@ Interlisp and how to access and use the restored Medley system.
 - [Content Authoring](#content-authoring)
   - [Editing Existing Pages](#editing-existing-pages)
   - [Adding New Pages](#adding-new-pages)
+  - [Social Share Images and Metadata](#social-share-images-and-metadata)
+  - [Structured Data (JSON-LD)](#structured-data-json-ld)
+  - [Meta Descriptions](#meta-descriptions)
   - [Adding or Updating the Comments Page](#adding-or-updating-the-comments-page)
   - [Bibliography Data](#bibliography-data)
 - [Local Development](#local-development)
@@ -120,6 +123,63 @@ type: docs
 
 The content follows the preamble and is written using [Markdown](https://www.markdownguide.org/tools/hugo/).
 
+### Social Share Images and Metadata
+
+When a page is shared on social platforms (Bluesky, Mastodon, Facebook, LinkedIn, Slack, etc.), the preview card is built from the page's Open Graph metadata. Docsy generates these tags automatically, so authors normally don't need to do anything.
+
+- **Default image:** `config/_default/params.yaml` sets `images: [images/og-default.png]`, which is used for every page that does not specify its own. The image lives at `static/images/og-default.png` and is 1200x630 px.
+- **Per-page override:** add an `images` list to the page front matter. Place a 1200x630 px image under `static/` and reference it site-relative:
+
+  ```markdown
+  ---
+  title: Medley Goals
+  weight: 10
+  type: docs
+  images: ["images/medley-goals-share.png"]
+  ---
+  ```
+
+- **Alt text:** the `og:image:alt` and `twitter:image:alt` values are generated from the page title automatically (see `layouts/_partials/hooks/head-end.html`).
+- **Mastodon attribution:** `config/_default/params.yaml` sets `fediverse_creator: "@interlisp@fosstodon.org"`, which is emitted as a `fediverse:creator` meta tag so Mastodon (4.3+) credits the project account on shared links. Override per page with a `fediverse_creator` front matter value if needed.
+
+Bluesky and Mastodon build their previews from Open Graph tags only (they ignore `twitter:*`). Mastodon caches a card per status, so edit or repost to refresh it. Bluesky generates the card when a post is composed, so metadata changes only affect new posts.
+
+### Structured Data (JSON-LD)
+
+The site emits [schema.org](https://schema.org) JSON-LD so search engines can show rich results (article cards, breadcrumbs). The partials live in `layouts/_partials/` and are wired into `layouts/_partials/hooks/head-end.html`; each one guards itself, so authors normally don't need to do anything.
+
+| Schema | Where it appears | Source partial |
+|--------|------------------|----------------|
+| `Organization` | Home page only | `schema-organization.html` |
+| `Article` | Every content page (not bibliography entries or sections) | `schema-article.html` |
+| `BreadcrumbList` | Every page except the home page and 404 | `schema-breadcrumb.html` |
+| Bibliography types | `content/en/history/bibliography/**` | `bibliography-json-ld.html` |
+
+- **Article metadata** is derived automatically: `headline` from the title, `description` from the page description, `datePublished` from `date`, `dateModified` from the file's last git change (`enableGitInfo: true`), and `author`/`publisher` from `site.Params.author`.
+- **Validate locally** with the test suite (`tests/test_site_jsonld.py`) and, before release, with Google's [Rich Results Test](https://search.google.com/test/rich-results).
+
+### Meta Descriptions
+
+The `<meta name="description">` tag is generated for every page by `layouts/_partials/page-description.html`. It is what search engines may show beneath a page title in results, so it should be a clear, compelling summary that includes the page's main topic.
+
+**Authoring rules:**
+
+- Add a `description:` field to a page's front matter. Aim for **150–160 characters** (about one to two sentences).
+- Make it **unique** — avoid reusing the same text across pages.
+- Describe what the reader will find and include the primary keyword naturally. Do not stuff keywords or simply repeat the title.
+
+  ```markdown
+  ---
+  title: History
+  description: "Explore the history of Interlisp, the pioneering Lisp software development environment born at Xerox PARC in the 1970s and 1980s."
+  ---
+  ```
+
+**Fallback behavior** (when a page has no `description:`): the partial uses, in order, the page's `description`, then its auto-generated summary, then a generated description (for bibliography, taxonomy, and term pages), and finally the site-wide default from `config/_default/params.yaml`. Any description longer than 160 characters is truncated at a word boundary. Relying on the fallback is fine for minor pages, but hand-written descriptions are strongly preferred for anything in the navigation.
+
+- **Bibliography entries** are described automatically from the entry's title and abstract (or authors); you do not need to add `description:` to generated entries. Hand-written pages that merely live under the bibliography tree (e.g. `intake/`, `zotero-resources/`, which set `type: docs`) are *not* generated entries and still need their own `description:`; the test identifies generated entries from the rendered `class="bibliography-entry"` marker rather than the URL.
+- **Validate locally** with `tests/test_meta_descriptions.py`.
+
 ### Adding or Updating the Comments Page
 
 The *comments* page ("What people are saying") collects quotes and screenshots that discuss Medley Interlisp. We preserve Twitter and Mastodon posts as images along with links to the post to protect against content being deleted from social platforms.
@@ -460,6 +520,11 @@ gcs_engine_id: 33ef4cbe0703b4f3a
 
 Search results are rendered using the `search.html` layout template.
 
+The search page is intentionally kept out of search-engine indexes: `robots.txt` disallows
+`/search/`, and `content/en/search.md` sets `robots = "noindex"` (which also excludes it from the
+sitemap). The page is a thin wrapper around the Google Custom Search widget with no content of its
+own.
+
 **Updating Search:**
 
 Modifying search scope requires updating the Google Custom Search engine settings via the [Programmable Search Engine Dashboard](https://programmablesearchengine.google.com). Access is restricted. To suggest changes, open an issue: [Search Engine Issue](https://github.com/interlisp/medley/issues/new?template=bug_report.md&title=Search_Engine_Issue)

diff --git a/archetypes/default.md b/archetypes/default.md
@@ -2,5 +2,10 @@
 title: "{{ replace .Name "-" " " | title }}"
 date: {{ .Date }}
 draft: true
+# Optional: override the default social share image (Open Graph / Twitter Card).
+# Place the file under static/ and reference it site-relative, e.g.:
+# images: ["images/my-share-image.png"]
+# Optional: override the Mastodon fediverse:creator attribution for this page.
+# fediverse_creator: "@interlisp@fosstodon.org"
 ---
 
diff --git a/config/_default/params.yaml b/config/_default/params.yaml
@@ -6,8 +6,16 @@
 # Set Google Analytics to use GA4
 disableGtagForUniversalAnalytics: false
 
-# First one is picked as the Twitter card image if not set on page.
-# images = ["images/project-illustration.png"]
+# Default social share image (Open Graph / Twitter Card).
+# The first entry is used when a page does not set its own `images` front matter.
+# Recommended size: 1200x630 px. Served from static/, so the path is site-relative.
+images:
+  - images/og-default.png
+
+# Mastodon (4.3+) attribution for shared links. Emitted as
+# <meta name="fediverse:creator"> by layouts/_partials/hooks/head-end.html.
+# Override per page with a `fediverse_creator` front matter value.
+fediverse_creator: "@interlisp@fosstodon.org"
 
 # Menu title if your navbar has a versions selector to access old versions of your site.
 # This menu appears only if you have at least one [params.versions] set.

diff --git a/content/en/_index.md b/content/en/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Medley Interlisp Project
+description: "Reviving Interlisp-D, the pioneering Lisp software environment created at Xerox PARC. Explore Medley's history, documentation, and how to run it today."
 aliases:
  - /hugo
 ---

diff --git a/content/en/history/_index.md b/content/en/history/_index.md
@@ -1,5 +1,6 @@
 ---
 title: History
+description: "Trace how Interlisp evolved from an interactive programming tool into Interlisp-D and Medley, and the research fields it helped pioneer, from AI to GUIs."
 weight: 500
 type: docs
 aliases:

diff --git a/content/en/history/bibliography/intake/_index.md b/content/en/history/bibliography/intake/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Interlisp Bibliography Intake Guide
+description: "Not sure whether a document belongs in the Interlisp Bibliography? This guide explains the collection's scope, how to submit an item, and what to include."
 weight: 1
 type: docs
 # Explicitly visible in the sidebar: the parent bibliography section's

diff --git a/content/en/history/bibliography/zotero-resources/_index.md b/content/en/history/bibliography/zotero-resources/_index.md
@@ -1,6 +1,6 @@
 ---
 title: "Zotero Type Mapping Reference"
-description: "How Interlisp Zotero bibliography types map to CSL JSON and Schema.org vocabulary"
+description: "For Interlisp Zotero contributors: how each bibliography item type is classified and mapped through the processing pipeline to CSL JSON and Schema.org."
 type: docs
 toc_hide: false
 ---

diff --git a/content/en/history/glossary/_index.md b/content/en/history/glossary/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Glossary
+description: "Confused by the many names used for Interlisp over the decades? This glossary untangles Medley, Interlisp-D, and related terms with clear definitions."
 aliases:
  - /glossary/
  - /medley/project/vocabulary/

diff --git a/content/en/history/in-memoriam.md b/content/en/history/in-memoriam.md
@@ -1,5 +1,6 @@
 ---
 title: In Memoriam
+description: "A tribute to the people whose work shaped Interlisp, remembering their contributions to the language, its development tools, and the community around it."
 weight: 100
 type: docs
 ---

diff --git a/content/en/history/links.md b/content/en/history/links.md
@@ -1,5 +1,6 @@
 ---
 title: Interlisp History Resources
+description: "Where to find Interlisp artifacts online: a curated set of archives, collections, and computing-history resources the Medley team draws on for research."
 weight: 95
 type: docs
 ---

diff --git a/content/en/history/timeline/_index.md b/content/en/history/timeline/_index.md
@@ -1,5 +1,6 @@
 ---
 title:  Interlisp Timeline
+description: "Follow the milestones of Interlisp's development year by year, from its earliest experiments through the rise of Interlisp-D and the Medley era, and beyond."
 type: docs
 weight: 50
 aliases:

diff --git a/content/en/privacy.md b/content/en/privacy.md
@@ -1,5 +1,6 @@
 ---
 title: Interlisp.org Privacy Statement
+description: "What data Interlisp.org collects and why, how cookies and Google Analytics are used, and the choices visitors have about their information and privacy."
 url: /privacy/
 type: docs
 weight: 30

diff --git a/content/en/project/_index.md b/content/en/project/_index.md
@@ -1,5 +1,6 @@
 ---
 Title: The Medley Interlisp Project
+description: "Why we are bringing Medley back to life, what we hope to accomplish, and the state of the work: an introduction to the project and its ambitions for the future."
 weight: 2
 type: docs
 aliases:

diff --git a/content/en/project/comments/_index.md b/content/en/project/comments/_index.md
@@ -2,7 +2,7 @@
 title: What people are saying
 weight: 20
 type: docs
-description: Comments on Interlisp and this project
+description: "How people talk about Interlisp online: a running collection of blog posts, social media threads, and reflections, with a way to submit new links of your own."
 aliases: 
  - /medley/about/comments/
 ---

diff --git a/content/en/project/credits.md b/content/en/project/credits.md
@@ -1,5 +1,6 @@
 ---
 title: Credits
+description: "Acknowledging the many people who built Interlisp over the decades, and the challenge of crediting work that spanned several companies across many years."
 weight: 80
 type: docs
 ---

diff --git a/content/en/project/donate.md b/content/en/project/donate.md
@@ -1,5 +1,6 @@
 ---
 title: Donate
+description: "Help sustain the Interlisp revival. See why your gift matters, what it funds, and the different ways you can contribute to keeping Medley available to everyone."
 weight: 15
 type: docs
 ---

diff --git a/content/en/project/faqs.md b/content/en/project/faqs.md
@@ -1,5 +1,6 @@
 ---
 title: FAQs
+description: "Straightforward answers to the questions people ask most often when getting started with Medley Interlisp or working in it day to day, from editors to printing."
 weight: 20
 type: docs
 ---

diff --git a/content/en/project/getInvolved/_index.md b/content/en/project/getInvolved/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Get Involved
+description: "There is a place for every skill level in the Interlisp revival. Find the route that fits you, whether you code, test, document, or help spread the word."
 weight: 11
 type: docs
 aliases:

diff --git a/content/en/project/organization.md b/content/en/project/organization.md
@@ -1,5 +1,6 @@
 ---
 title: Organization
+description: "Who runs the project and how it is structured, including the non-profit that holds its charitable mission and supports its scientific and technical goals."
 weight: 1000
 type: docs
 ---

diff --git a/content/en/project/partners/SHFT.md b/content/en/project/partners/SHFT.md
@@ -1,5 +1,6 @@
 ---
 title: Software History Futures and Technologies SHFT
+description: "A University of Alberta research group studying software history partners with us to make Interlisp's innovations and context easier to explore and understand."
 weight: 20
 type: docs
 ---

diff --git a/content/en/project/partners/SPN.md b/content/en/project/partners/SPN.md
@@ -1,5 +1,6 @@
 ---
 title: Software Preservation Network
+description: "Why we joined a network of libraries, archives, and universities working to keep software usable for the long term, and what that partnership involves."
 weight: 20
 type: docs
 ---

diff --git a/content/en/project/partners/_index.md b/content/en/project/partners/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Organizational Partners
+description: "The organizations and academic groups collaborating with the Medley Interlisp Project, and how these partnerships advance software preservation and research."
 weight: 18
 type: docs
 aliases:

diff --git a/content/en/project/partners/educopia.md b/content/en/project/partners/educopia.md
@@ -1,5 +1,6 @@
 ---
 title: Educopia
+description: "The non-profit behind the Software Preservation Network, and the governance and community-building resources it offers to preservation projects and communities."
 weight: 20
 type: docs
 aliases:

diff --git a/content/en/project/partners/interlisporg-inc.md b/content/en/project/partners/interlisporg-inc.md
@@ -1,5 +1,6 @@
 ---
 title: InterlispOrg
+description: "The non-profit corporation that funds and steers the revival, including its tax-exempt status, how it is governed, and how to support it financially today."
 weight: 25
 type: docs
 aliases:

diff --git a/content/en/project/reviving.md b/content/en/project/reviving.md
@@ -1,5 +1,6 @@
 ---
 Title: Reviving Medley
+description: "The technical decisions behind the revival: what it takes to bring a decades-old system forward, and the areas of work the project is tackling now and next."
 weight: 80
 type: docs
 ---

diff --git a/content/en/project/status/_index.md b/content/en/project/status/_index.md
@@ -1,5 +1,6 @@
 ---
 title: News and Status Reports
+description: "The latest news from the project — reports, interviews, and announcements — with an archive of how the revival has progressed year by year since 2020."
 type: docs
 weight: 2
 outputs:

diff --git a/content/en/project/status/reports/2021MedleyAnnualReport.md b/content/en/project/status/reports/2021MedleyAnnualReport.md
@@ -1,5 +1,6 @@
 ---
 title: 2021 Medley Interlisp Annual Report
+description: "The report on the project's founding year: early decisions, initial milestones, and the groundwork laid for restoring Medley and making it usable again."
 weight: 10
 type: docs
 aliases:

diff --git a/content/en/project/status/reports/2022MedleyAnnualReport.md b/content/en/project/status/reports/2022MedleyAnnualReport.md
@@ -1,5 +1,6 @@
 ---
 title: 2022 Medley Interlisp Annual Report
+description: "A year of milestones: what the team accomplished in 2022, the collaborations it formed, and how the preservation work advanced over the course of the year."
 weight: 9
 type: docs
 aliases:

diff --git a/content/en/project/status/reports/2023MedleyAnnualReport.md b/content/en/project/status/reports/2023MedleyAnnualReport.md
@@ -1,5 +1,6 @@
 ---
 title: 2023 Annual Report
+description: "The 2023 report details the year's achievements and the continuing effort to keep Interlisp usable, documented, and available to new audiences around the world."
 weight: 8
 type: docs
 aliases:

diff --git a/content/en/project/status/reports/2024MedleyAnnualReport.md b/content/en/project/status/reports/2024MedleyAnnualReport.md
@@ -1,5 +1,6 @@
 ---
 title: 2024 Medley Interlisp Annual Report
+description: "The 2024 report covers another year of porting, documenting, and improving Medley, along with the project's goals and priorities for the year ahead of us."
 weight: 7
 type: docs
 aliases:

diff --git a/content/en/project/status/reports/2025MedleyAnnualReport.md b/content/en/project/status/reports/2025MedleyAnnualReport.md
@@ -1,5 +1,6 @@
 ---
 title: 2025 Medley Interlisp Annual Report
+description: "Five years in: the 2025 report looks back at how far the revival has come and the work still ahead to keep Medley thriving on modern systems and gaining users."
 weight: 1
 type: docs
 aliases:

diff --git a/content/en/project/status/reports/_index.md b/content/en/project/status/reports/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Annual Reports
+description: "Browse every annual report in one place and follow the project's progress from its first year through the present day, with a link to each year's report."
 weight: 1
 type: docs
 ---

diff --git a/content/en/project/stories.md b/content/en/project/stories.md
@@ -1,5 +1,6 @@
 ---
 title: Our Stories
+description: "First-hand accounts from people who used Interlisp in its prime, recalling what made the environment special and why it still matters to them and to computing."
 weight: 40
 type: docs
 ---

diff --git a/content/en/search.md b/content/en/search.md
@@ -1,4 +1,6 @@
 +++
 title = "Search Results"
+description = "Search Interlisp.org to find documentation, history, software guides, and bibliography entries about Medley Interlisp and the historic Interlisp-D system."
 layout = "search"
+robots = "noindex"
 +++
diff --git a/content/en/software/_index.md b/content/en/software/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Software
+description: "Everything you need to start using Medley: choose between running it in your browser or installing it locally, then dig into the guides and documentation."
 type: docs
 aliases:
 

diff --git a/content/en/software/access-online/_index.md b/content/en/software/access-online/_index.md
@@ -1,5 +1,6 @@
 ---
 title: Access Medley Online
+description: "Try Medley instantly without installing anything. Learn what the online environment is suited for and what to keep in mind while you experiment with it."
 weight: 10
 type: docs
 aliases:

diff --git a/content/en/software/install-and-run/_index.md b/content/en/software/install-and-run/_index.md
@@ -1,5 +1,6 @@
----
+---
 title: Install and Run
+description: "Choose your platform and follow the guides to get Medley running on your own machine, with notes on supported systems and architectures, from x86_64 to ARM."
 aliases:
  - /medley/using/build/
  - /medley/using/running/

diff --git a/content/en/software/install-and-run/linux/_index.md b/content/en/software/install-and-run/linux/_index.md
@@ -1,5 +1,6 @@
----
+---
 title: Install and Run on Linux
+description: "Get Medley running on your Linux machine, including what the system requires and how to handle the most common distributions and desktop environments."
 linkTitle: Linux
 weight: 20
 type: docs

diff --git a/content/en/software/install-and-run/linux/linux-local-from-github.md b/content/en/software/install-and-run/linux/linux-local-from-github.md
@@ -1,5 +1,6 @@
----
+---
 title: Download WSL (Local Installation) Install Files from Github
+description: "Follow step-by-step instructions to download the local-installation Medley Interlisp release files from GitHub and install Medley on your Linux system."
 weight: 40
 toc_hide: true
 hide_summary: true

diff --git a/content/en/software/install-and-run/linux/linux-standard-from-github.md b/content/en/software/install-and-run/linux/linux-standard-from-github.md
@@ -1,5 +1,6 @@
----
+---
 title: Download WSL (Standard Installation) Install Files from Github
+description: "Follow step-by-step instructions to download the standard Medley Interlisp release files from GitHub and install Medley on your most recent Linux system."
 weight: 40
 toc_hide: true
 hide_summary: true

diff --git a/content/en/software/install-and-run/macos/_index.md b/content/en/software/install-and-run/macos/_index.md
@@ -1,5 +1,6 @@
----
+---
 title: Install and Run on MacOS
+description: "Set up Medley on your Mac, including the X11 software you will need first and a pointer to the download steps, for both Apple silicon and Intel systems."
 linkTitle: MacOS
 weight: 30
 type: docs

diff --git a/content/en/software/install-and-run/macos/macos-from-github.md b/content/en/software/install-and-run/macos/macos-from-github.md
@@ -1,5 +1,6 @@
----
+---
 title: Download MacOS Install File from Github
+description: "Follow the instructions to download the Medley Interlisp macOS install file from GitHub Releases and set up Medley on your Apple silicon or Intel Mac."
 weight: 40
 toc_hide: true
 hide_summary: true