forschung.stadtgeschichtebasel.ch

Open-source code of the digital research data platform for Stadt.Geschichte.Basel — a major historical research initiative hosted at the University of Basel.

🔎 Overview

Welcome to Stadt.Geschichte.Basel, a historical research project at the University of Basel in Switzerland, funded with over 9 million Swiss Francs from public and private sources, running from 2017 to 2025. It is a comprehensive digital and print project that aims to present the multifaceted history of Basel from its earliest beginnings to the present day. Visit Stadt.Geschichte.Basel to see how our digital portal brings Basel's history to life.

Stadt.Geschichte.Basel seeks to bridge research gaps and present historical findings in accessible formats. Our project encompasses an extensive nine-volume book series, an overview volume, a digital portal, and a digital platform for research data. Hosted at the University of Basel, this project aims to make historical research and insights accessible to scholars and the public like never before.

This repository contains the source code for the research data platform, built with CollectionBuilder-CSV, a static site generator based on Jekyll and deployed via GitHub Pages.
The collection data is maintained on the University of Bern’s Omeka S instance.

⚙️ Features

• Static Site Generator: Fast, scalable, minimal-maintenance architecture using Jekyll.
• Interactive Metadata Exploration: Timelines, filters, annotations, and visualizations.
• Inclusive Metadata Practices: Based on our Manual for Creating Non-Discriminatory Metadata.
• Accessibility-First Design: Compliant with WCAG, designed with Neurodiversity Design System guidelines in mind.
• Open Standards: Schema.org, Open Graph, EDTF support, and reusable modular components.

🔧 Project-Specific Extensions to CollectionBuilder

The technical basis for Stadt.Geschichte.Basel's research data platform is provided by CollectionBuilder, an open source framework for creating metadata-driven digital collections. CollectionBuilder is a project maintained by the University of Idaho Library's Digital Initiatives and the Center for Digital Inquiry and Learning (CDIL) following the Lib-Static methodology.

The basic theme is created using Bootstrap. Metadata visualizations are built using open source libraries such as DataTables, Spotlight gallery, lazysizes, Lunr.js and Leaflet. Object metadata is exposed using Schema.org and Open Graph protocol standards.

For more information on CollectionBuilder, visit the Docs.

Stadt.Geschichte.Basel has extended CollectionBuilder with some features that are not (yet) included in the CollectionBuilder project. These are the following extensions:

• List Visualization: In addition to wordclouds, fields can be visualized in a list including their frequencies.
• EDTF Timeline Page: Based on the existing solution, an enhanced timeline was created that supports year numbers in Extended Date/Time Format (EDTF).
• Item Layout "Geodata": Definition of a new display_template ("geodata"). An interactive map was created as a new item view to display geojson files.
• Item Layout "Table": Tabular data is read from csv files and displayed as an interactive table with search and filter features directly on the item page.
• Multi-Language Support for Theming: So far, German and Spanish are supported. English is the default language.
• Trigger Warning: To draw attention to possibly sensitive contents of the collection, a trigger warning has been added, which appears once when the page is visited.
• Report Button: A button has been added to the item view that allows the user to report incorrect data.
• Website Layout: The different collection display options were reorganized and are now accessible on a central collection page, with buttons to switch views. Webdesign adjustments and were incorporated with the Neurodiversity Design System in mind to provide a coherent visual appearance.
• GitHub Actions: GitHub actions have been added to check code for correct formatting and to automatically build the site, including processing the data from Omeka S.
• Use of prettier: All files were formatted using prettier.

🧱 Data Model

Metadata for items featured on the research data platform is provided according to a data model developed by the Stadt.Geschichte.Basel Research Data Management Team to meet the requirements of the wide range of sources used in the project. The data model (and the subsequent annotation process) follow the Manual for Creating Non-Discriminatory Metadata for Historical Sources and Research Data developed by Stadt.Geschichte.Basel.

The following chart illustrates the data model with metadata fields for a sample metadata object abb01313 that has one child media object m01313. If a metadata object has more than one child media object, the children ids are numbered consecutively: m01313_1, m01313_2 etc.

    classDiagram
    direction LR
        class metadata {
            id (abb01313)
            title
            [subject;subject]
            description
            temporal
            [isPartOf;isPartOf] (Data DOIs)
        }
        class media {
            id (m01313)
            title
            [subject;subject]
            description
            [abstract] (alt-attribute for alternative text)
            [creator] (incl. link to institution)
            [publisher] (incl. link to institution)
            date
            temporal
            type
            format
            extent
            [source] (source and catalogue link)
            language (ISO 639-2 code)
            [relation] (internal links, link to GitHub)
            rights
            license
        }
    metadata "n" --> "m" media
    style metadata stroke:#3a1e3e,fill:#fff,color:#3a1e3e
    style media stroke:#3a1e3e,fill:#fff,color:#3a1e3e

Loading

Warning

In Omeka, temporal refers to the period (e.g. “19th century”), while CollectionBuilder uses coverage for this purpose. Allowed values: Frühgeschichte, Antike, Mittelalter, Frühe Neuzeit, 19. Jahrhundert, 20. Jahrhundert, 21. Jahrhundert.

🚀 Getting Started

📋 Prerequisites

Ensure you have the following tools installed:

• Node.js and npm (for package management and build scripts)
• Ruby and bundler (for Jekyll)
• uv (for Python dependency management)

🔧 Installation

Option 1: Quick Setup (Recommended)

Use npm scripts to install all dependencies:

npm run setup

This will install Node.js dependencies, Ruby gems, and Python packages.

Option 2: Manual Installation

Install dependencies step by step:

# Install npm dependencies
npm install

# Install Ruby gems
npm run install:ruby
# or manually: bundle config set --local path 'vendor/bundle' && bundle install

# Install Python dependencies
npm run install:python
# or manually: uv sync

⚙️ Configuration

Create a .env file in the root directory to configure API access:

OMEKA_API_URL=https://omeka.unibe.ch/api
KEY_IDENTITY=YOUR_KEY_IDENTITY
KEY_CREDENTIAL=YOUR_KEY_CREDENTIAL
ITEM_SET_ID=10780

Note

Replace YOUR_KEY_IDENTITY and YOUR_KEY_CREDENTIAL with your actual credentials for the Omeka S API. You can find these in the Omeka S instance under "Settings" > "API Keys". The ITEM_SET_ID is the ID of the collection you want to process, which can be found in the URL of the collection page.

📊 Data Processing

Process the collection data from Omeka S:

npm run populate

🛠 Development

Start the local development server:

npm run dev
# or alternatively: npm run serve
# or manually: bundle exec jekyll serve

The site will be available at http://127.0.0.1:4000.

📦 Production Build

Build the site for production:

npm run build:production
# or manually: rake deploy

For a standard Jekyll build without production optimizations:

npm run build
# or manually: bundle exec jekyll build

🧹 Available npm Scripts

Script	Description
npm run setup	Complete setup: install all dependencies
npm run install:ruby	Install Ruby gems with bundler
npm run install:python	Install Python dependencies with uv
npm run install:all	Install both Ruby and Python dependencies
npm run dev	Start Jekyll development server
npm run serve	Alias for dev
npm run build	Build Jekyll site
npm run build:production	Build site with production settings
npm run populate	Process data from Omeka S API
npm run clean	Remove generated data and objects
npm run format	Format code with Prettier
npm run check	Check code formatting

💡 Usage Examples

Common Workflows

1. First-Time Setup

# Clone the repository
git clone https://github.com/Stadt-Geschichte-Basel/forschung.stadtgeschichtebasel.ch.git
cd forschung.stadtgeschichtebasel.ch

# Install all dependencies
npm run setup

# Start development server
npm run dev

2. Daily Development

# Start the development server (with auto-reload)
npm run dev

# Make changes to files in:
# - _layouts/     (page templates)
# - _includes/    (reusable components)
# - pages/        (site pages)
# - assets/       (CSS, JavaScript, images)

# Jekyll automatically rebuilds when files change
# Refresh your browser to see updates

3. Working with Data

# Fetch latest data from Omeka S
npm run populate

# Clean old data before fetching new
npm run clean && npm run populate

# View generated metadata
cat _data/sgb-metadata-csv.csv

4. Code Formatting

# Check code formatting (useful before committing)
npm run check

# Auto-format all code
npm run format

# Format and commit
npm run format && git add . && git commit -m "Format code"

5. Building for Production

# Build with production optimizations
npm run build:production

# Or use standard build
npm run build

# Output is in _site/ directory
ls -la _site/

Advanced Workflows

Working on a Specific Feature

# Create a feature branch
git checkout -b feature/my-new-feature

# Make changes and test locally
npm run dev

# Format code
npm run format

# Commit changes
git add .
git commit -m "Add: description of changes"

# Push to GitHub
git push origin feature/my-new-feature

Testing Different Ruby Versions

# Switch Ruby version with rbenv
rbenv install 3.1.0
rbenv local 3.1.0

# Reinstall dependencies
bundle install

# Test the site
npm run dev

Debugging Build Issues

# Run Jekyll with verbose output
bundle exec jekyll build --verbose --trace

# Check Jekyll doctor
bundle exec jekyll doctor

# Clean and rebuild
rm -rf _site .jekyll-cache
bundle exec jekyll build

Working Without Omeka API Access

If you don't have Omeka API credentials:

# Use existing sample data (if available)
# The repository may include sample metadata files

# Or work on frontend/template changes only
npm run dev

# Your changes to layouts and styling will still work

Configuration Changes

Changing Site Title

Edit _config.yml:

title: Your Custom Title
tagline: Your custom tagline
description: Your custom description

Restart the dev server after config changes:

# Stop with Ctrl+C, then restart
npm run dev

Adding a New Page

# Create a new page in pages/
cat > pages/my-new-page.md << 'EOF'
---
title: My New Page
layout: page
permalink: /my-new-page/
---

# My New Page Content

Your content here...
EOF

# The page is now available at /my-new-page/

Customizing Theme Colors

Edit _data/theme.yml:

# Primary colors
primary-color: "#3a1e3e"
secondary-color: "#e8b4b8"
link-color: "#3a1e3e"
# Or edit CSS directly in assets/css/

📖 Documentation

This project has comprehensive documentation to help you get started and contribute:

For Users

• README.md (this file) - Project overview and quick start
• Website - Live platform

For Contributors

• SETUP.md - Detailed setup guide for new contributors
• CONTRIBUTING.md - How to contribute to the project
• TROUBLESHOOTING.md - Common issues and solutions
• API.md - API documentation and data integration guide

Technical Documentation

• docs/ - Technical documentation directory
  • docs/index.md - Documentation index and navigation
  • docs/metadata.md - Metadata structure and fields
  • docs/plugins.md - Jekyll plugins documentation
  • docs/maps.md - Geographic visualization
  • docs/localization.md - Multi-language support
  • And many more technical guides

External Resources

• CollectionBuilder Documentation - Framework documentation
• Jekyll Documentation - Static site generator
• Bootstrap Documentation - Frontend framework

🐕‍🦺 Support

This project is maintained by @Stadt-Geschichte-Basel. Please understand that we won't be able to provide individual support via email. We believe that help is much more valuable if it's shared publicly, so that more people can benefit from it.

Type	Platforms
🚨 Bug Reports	GitHub Issue Tracker
🎁 Feature Requests	GitHub Issue Tracker
🛡 Report a security vulnerability	GitHub Issue Tracker
💬 General Questions	GitHub Discussions
📚 Documentation Issues	GitHub Issue Tracker

🤝 Contributing

We welcome contributions! Please read our CONTRIBUTING.md for guidelines on submitting issues and pull requests.

📌 Versioning

We use Semantic Versioning. Available versions: GitHub Tags

👥 Authors

• Moritz Mähr — @maehr
• Nico Görlich — @koilebeit
• Moritz Twente — @mtwente

See the full list of contributors.

📜 License

This codebase is released under the MIT License. Note: Content and media objects on forschung.stadtgeschichtebasel.ch are not included under this license. See each item's metadata for usage rights.

External libraries under assets/lib/ are licensed separately.