Interlisp.org Home Page

The documentation repository for https://interlisp.org, the restoration project for the Interlisp ecosystem.

The collection of pages provides information on the restoration effort, Medley, Interlisp and how to access and use the restored Medley system.

Table of Contents

• Getting Started
  • Quick Start
  • Prerequisites
• Content Authoring
  • Editing Existing Pages
  • Adding New Pages
  • Adding or Updating the Comments Page
  • Bibliography Data
• Local Development
  • Installing Hugo
  • Running the Development Server
• CI/CD and Deployment
  • gh-pages GitHub Workflow
  • Environment Variables
  • Deploying a Staging Site
• Reference
  • Repository Layout
  • Dependencies
  • Search Configuration
• Contact and Support
• License

---

Getting Started

The website is built using the Hugo static site generator and the Docsy technical documentation theme. Both sites contain extensive documentation on setup and maintenance.

Quick Start

For experienced users who want to get started quickly:

# Clone the repository
git clone https://github.com/Interlisp/Interlisp.github.io.git
cd Interlisp.github.io

# Fetch bibliography data (required for build)
./scripts/update_bibliography.sh

# Start local development server
hugo server -e development

Then open http://localhost:1313 in your browser.

Prerequisites

Before working with this repository, ensure you have the following installed:

Tool	Version	Purpose
Hugo Extended	v0.145.0+	Static site generator
Go	1.24+	Required for Hugo modules
Node.js & npm	Latest LTS	PostCSS and autoprefixer
jq	Latest	Bibliography JSON processing
curl, wget	System default	Script downloads

Verify installations:

hugo version      # Should show "extended" and v0.145.0+
go version        # Should show 1.24+
node --version    # Should show v18+ or later
jq --version      # Any recent version

---

Content Authoring

This section covers how to add and edit content on the Interlisp.org website.

General workflow:

1. Clone the Interlisp.github.io repository
2. Edit or add new pages
3. Validate the changes by running Hugo locally
4. Add, commit and push the updates back to the repository
5. Once merged into main, GitHub Actions will rebuild and update the website

Editing Existing Pages

Content is located in the content/en directory. At present, English is the only language supported. If that changes in the future, additional language subdirectories can be added to the content directory.

Existing pages are written using Markdown and can easily be edited. Updates can be submitted as a pull request and, upon approval, will be merged into the main branch and deployed to the website.

Adding New Pages

Each page must have a preamble section that provides metadata for the Hugo engine:

---
title: Medley Goals
weight: 10
type: docs
---

Field	Description
title	The displayed title for the page
weight	Positioning of the page (lower numbers appear first). Multiple pages can share the same weight.
type	Page type. Currently all pages are of type docs

The content follows the preamble and is written using Markdown.

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.

To add a new entry to the comments page (content/en/project/comments/_index.md):

{{< imgproc AuthorName_YYYYMMDD Resize "550x803">}} <a href="https://example.com/post-url">Link to post</a> {{< /imgproc >}}

• Use the imgproc shortcode to render and size the image
• Name images with the author and date (e.g., PaulFord_20211214.jpg)
• Store image files in the same directory as _index.md
• Posts that are no longer accessible will have their links removed but the content will be preserved

Bibliography Data

The website maintains an extensive bibliography. The information displayed on the webpage is a snapshot of the data stored in our online Zotero Group Library. The Zotero library is our source of truth.

A GitHub Action runs daily to check if the Zotero library has changed. If so, a script downloads and rebuilds the bibliography pages.

To fetch the bibliography locally:

cd scripts
./update_bibliography.sh

This script retrieves the bibliography from Zotero, formats it appropriately, and places the individual JSON files in static/data/bibItems/.

---

Local Development

Local testing of updates requires running Hugo locally.

Installing Hugo

Instructions for installing Hugo on various operating systems are at: Installing Hugo. Interlisp uses the extended version of Hugo.

For Ubuntu:

wget https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_extended_0.155.3_linux-amd64.deb

sudo dpkg -i hugo_extended_0.155.3_linux-amd64.deb

Verify installation:

hugo version
# Expected output:
hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio

Running the Development Server

1. Ensure bibliography data is available (see Bibliography Data)

2. Start the Hugo development server:

hugo server --cleanDestinationDir  --disableFastRender --renderToMemory

Hugo will automatically download the Docsy theme and its dependencies as Hugo modules. Expected output:

Watching for changes in <project-root>/archetypes, <project-root>/assets/{css,icons,js,scss}, <project-root>/content/en/{history,project,software}, <project-root>/layouts/{_default,_partials,_shortcodes,bibliography,redirect}, <project-root>/package.json, <project-root>/static/{Resources,data,docs,documentation,favicons}
Watching for config changes in <project-root>/config/_default, <project-root>/config/development, <project-root>/go.mod
Start building sites … 
hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio

WARN  WARNING: 298 sidebar entries have been truncated. To avoid this, increase `params.ui.sidebar_menu_truncate` to at least 398 (from 100) in your config file. Section: /history/bibliography

                  │  EN  
──────────────────┼──────
 Pages            │ 1165 
 Paginator pages  │    0 
 Non-page files   │   66 
 Static files     │   79 
 Processed images │   50 
 Aliases          │   51 
 Cleaned          │    0 

Built in 1169 ms
Environment: "development"
Serving pages from memory
Web Server is available at //localhost:1313/ (bind address 127.0.0.1) 
Press Ctrl+C to stop

3. Open http://localhost:1313 to review the locally running website

4. For additional debugging information, use --logLevel debug

Once validated, create a pull request to merge your changes into the main branch.

---

CI/CD and Deployment

This section covers automated builds and deployment processes.

gh-pages GitHub Workflow

Building the website is driven by a GitHub workflow (.github/workflows/gh-pages.yml).

Triggers:

• push to main — updates to the Interlisp.org website
• pull_request to main — validates changes before merge (builds but does not deploy)
• Scheduled execution — ensures the bibliography remains consistent with Zotero
• Manual execution — via the Actions panel in GitHub

Workflow Jobs:

The workflow consists of four jobs:

1. validate-docs — Verify Documentation Consistency

Runs on push and pull_request events to ensure that README.md references the correct Hugo version. Checks that:

• The Hugo badge displays the version defined in HUGO_VERSION
• The README.md installation instructions use the correct version

This job prevents documentation drift from the actual build configuration.

2. hugo-version — Expose the Hugo Version

Reads the HUGO_VERSION environment variable and exposes it as a job output. The env context is not available in a reusable workflow's with: block, so the version is surfaced here instead. Keeping it in the workflow env means version bumps are ordinary, reviewed pull requests.

3. build — Build the Website and Run the Tests

Delegates to the org-level reusable workflow (Interlisp/shared-workflows/.github/workflows/build-site.yml), which:

• Queries the Zotero REST API for the bibliography version and caches the bibliography, running update_bibliography.sh to download and process a new copy whenever the version has changed (a cache miss)
• On scheduled runs, skips the build when the bibliography is unchanged (exposed via the workflow's skipped output)
• Runs Hugo Extended with the build environment passed as an input (-e production for this repository)
• Runs the full test suite:
  • Content-integrity and bibliography JSON-LD suites against a testing-environment build (which mounts bibliography test fixtures)
  • Build-integrity tests (test_hugo_build.py) against the production output
• Uses the GitHub upload-pages-artifact action to package and store the ./public directory contents for deployment

4. deploy — Deploy to GitHub Pages

Takes the output of the build step and deploys it to GitHub Pages using the GitHub deploy-pages action. Skipped on pull requests and when the build was skipped because the bibliography was already current.

Environment Variables

The following repository variables control the build and deployment process:

Variable	Description	Values	Default
HUGO_ENVIRONMENT	Build environment used by the production workflow	development, staging, production	production
HUGO_VERSION	Hugo version used in CI/CD	Semantic version (e.g., 0.155.3)	Set in workflow

HUGO_ENVIRONMENT is resolved in .github/workflows/gh-pages.yml and passed as the hugo-environment input to the shared build workflow. The staging repository always builds with the staging environment.

Environment-specific behavior:

Environment	Analytics	Crawlers	Use Case
production	Enabled	Allowed	Live interlisp.org site
staging	Disabled	Blocked	PR previews and testing
development	Disabled	N/A	Local development

Deploying a Staging Site

Every pull request to main is automatically deployed to a per-PR staging preview. A dedicated repository, Interlisp/Interlisp.staging, acts as the deployment target. Each PR is served from a unique subdirectory of that repository's GitHub Pages site:

Deployment	URL
Staging root	https://interlisp.github.io/Interlisp.staging/
PR #123 preview	https://interlisp.github.io/Interlisp.staging/pr-123/

When a PR is opened or updated, the production workflow (gh-pages.yml) triggers the deploy-preview workflow in the staging repository, which:

1. Checks out the PR's head commit
2. Builds the site using the shared org-level workflow (Interlisp/shared-workflows/.github/workflows/build-site.yml)
3. Deploys the result to the pr-<N>/ subdirectory
4. Posts the preview URL as a comment on the PR

When a PR is closed or merged, preview-cleanup.yml triggers the remove-preview workflow in the staging repository to delete the subdirectory.

Because the build logic lives in the org-level reusable workflow, production and staging are always built the same way. The staging environment uses config/staging/hugo.yaml, which sets a baseURL for the staging site and disables production-only behavior such as search-engine crawling.

---

Reference

Repository Layout

The repository follows the standard Hugo directory structure:

Directory	Purpose
.github/workflows	GitHub Actions workflow (gh-pages.yml)
assets/	Custom global resources (CSS, JS, icons, SCSS)
config/	Site configuration for different environments
content/en/	All website content (English only)
layouts/	Hugo layout templates and overrides
static/	Files copied directly to the built site

Key subdirectories:

assets/ — Custom resources

• css/ — Third-party CSS files
• icons/ — SVG Interlisp-D logo (logo.svg)
• js/ — Custom and third-party JavaScript
• scss/ — Custom SCSS files
  • _styles_project.scss — Project-specific styles
  • _variables_project.scss — Docsy theme variable overrides

config/ — Environment configurations

• _default/ — Shared settings across all environments
• development/ — Local development settings
• staging/ — Staging site settings
• production/ — Production site settings

layouts/ — Template overrides

• _partials/ — Partial templates (favicons, footer, head, meta descriptions)
• _shortcodes/ — Hugo shortcodes (cover block, image gallery)
• bibliography/ — Bibliography section templates
• redirect/ — Redirect page template

static/ — Static files

• data/bibItems/ — Bibliography JSON files (generated, not in Git)
• documentation/ — PDF files referenced in the website
• favicons/ — Favicon files (SVG, ICO, PNG)
• Resources/ — Site resources including watermark logo
• CNAME — Custom domain configuration

Dependencies

Hugo Modules (go.mod):

Module	Version	Purpose
google/docsy	v0.14.3	Technical documentation theme
docsy/dependencies	v0.7.2	Docsy's required dependencies

Hugo modules are automatically downloaded when you run hugo server or hugo build.

npm Packages (package.json):

Package	Purpose
autoprefixer	Adds vendor prefixes to CSS for browser compatibility
hugo-extended	Hugo binary for npm-based workflows
postcss / postcss-cli	CSS transformation pipeline
jquery	JavaScript library used by some Docsy components
tabpanel	Accessible tab panel widget

Install npm dependencies with npm install (optional for local development).

Search Configuration

The site uses Google Custom Search to provide search results encompassing:

• The Interlisp.org website
• Interlisp GitHub repositories
• Discussion groups for Medley and Interlisp

The search engine is configured in config/_default/params.yaml:

gcs_engine_id: 33ef4cbe0703b4f3a

Search results are rendered using the search.html layout template.

Updating Search:

Modifying search scope requires updating the Google Custom Search engine settings via the Programmable Search Engine Dashboard. Access is restricted. To suggest changes, open an issue: Search Engine Issue

---

Contact and Support

• Report Issues: GitHub Issues — Report bugs or request features for the website
• Medley Interlisp Issues: Medley Repository — For issues related to Medley itself
• Discussions: Interlisp Discussions — Community discussions and questions
• Mailing List: interlisp@googlegroups.com — General Interlisp community discussion

License

This project is licensed under the MIT License — see the LICENSE file for details.

Copyright (c) 2026 Interlisp.org