Open Research Data

GitHub Template for FAIR and Open Research Data

Transforming research documentation from static afterthought into living, executable environments.

This template provides an infrastructure for documenting, publishing, and archiving research data in line with the principles of FAIR and open science. It is independent of data type or format and implements best practices as outlined in The Turing Way. Core components include automated release management, integrated archiving with Zenodo, structured documentation via Quarto, and long-term accessibility through GitHub Pages.

[!IMPORTANT] This README.md describes the template repository itself. If you created a new repository from this template, start with TODO.md, then customize the project-facing template files: CITATION.template.cff, CODE_OF_CONDUCT.template.md, SECURITY.template.md, README.template.md, and CHANGELOG.template.md, and rename them into place as directed there.

🤝 Academic Recognition

This approach was presented at the Digital Humanities Tech Symposium (DHTech) 2025 and exemplifies how reusable templates can address persistent challenges in research data management.

Mähr, M., & Twente, M. (2025). One Template to Rule Them All: Interactive Research Data Documentation with Quarto. Digital Humanities Tech Symposium, NOVA University Lisbon. https://maehr.github.io/one-template-to-rule-them-all/.

Why use a template (even for small datasets)?

Conventional data publication as static supplementary files offers limited reproducibility and reusability. This template extends such practices by providing:

📊 Executable narratives that embed code outputs directly into documentation
🚀 Automated deployment and testing that reduces technical overhead
🏛️ Integrated archiving with DOI through seamless Zenodo integration
📈 Scalability and consistency across diverse project types and domains
🔒 Enhanced security with automated vulnerability monitoring
🤝 Community standards following accepted ethics and collaboration practices

Features

Open Research Data

Citable via the template DOI, the live CITATION.cff, and the downstream CITATION.template.cff
Automatic long-term archiving with Zenodo, plus a commit-ready rendered site archive for tagged snapshots
Licensed under AGPL 3.0 and CC BY 4.0 according to The Turing Way
Template for reporting data issues via github/ISSUE_TEMPLATE/data_issue_report.yml

Documentation

README.md following www.makeareadme.com and The Turing Way
CHANGELOG.md for template release notes and CHANGELOG.template.md as the downstream project scaffold
Automated changelog generation with git-cliff
Machine-readable project metadata in package.json with npm
Accessible documentation with GitHub Pages and Quarto

Consistency

Code formatting with Prettier for general files, Ruff for Python, and styler and lintr for R
Python type checking with ty
Python dependency management with uv
R dependency management with renv
Commit messages following Conventional Commits enforced via prek
Versioning following Semantic Versioning
Workflow based on fork and pull with GitHub branch protection
Issue tracking via issue templates
File and folder naming conventions following The Turing Way

Security

SECURITY.md following GitHub guidelines, with SECURITY.template.md for downstream projects
Vulnerability monitoring with GitHub Security Alerts
Repository integrity enforced via GitHub branch protection

Ethics

CODE_OF_CONDUCT.md following the Contributor Covenant, with CODE_OF_CONDUCT.template.md for downstream projects

Selected Use Cases

The template has been applied across domains including public history, political science, digital humanities, and teaching infrastructures. The examples below come from the “One Template to Rule Them All” presentation and now call out the parts that coding agents can help automate.

🔬 Research Data Documentation

Project	Preview
Stadt.Geschichte.Basel RDM Project documentation platform combining research data management with public history outreach; agents can update metadata, maintain setup checklists, and validate publication-ready docs.
sgb-figures Reproducible code and annotated data for publication-ready visualisations of research data; agents can keep captions, changelog entries, and formatting in sync with analytical updates.

📊 Reproducible Research Workflows

Project	Preview
nordatlantisk-ft Voting records from the parliament of Denmark with complete data scraping and analysis pipeline; agents can scaffold scrapers, refresh documentation, and run formatting before release.
maxvogt-analysis Multi-step data compilation workflow documentation; agents can keep processing notes, metadata edits, and changelog updates aligned across the pipeline.
Modelling Marti Topic modeling project with interactive visualizations and multimedia content as narrative elements; agents can automate notebook-to-doc updates, link checks, and release preparation.

🎓 Academic Events & Teaching

Project	Preview
Digital History Switzerland 2024 Conference website with program, abstracts, and participant information; agents can batch-edit schedules, validate links, and keep publication assets consistent.
Digital Humanities Bern Department hub featuring news, events, and course information; agents can maintain navigation, announcement pages, and formatting checks for multi-page sites.
Decoding Inequality 2025 University course website with syllabus and materials; agents can help update teaching materials, sync metadata, and prepare changelog-ready release notes.

📚 Living Publications & Handbooks

Project	Preview
Non-discriminatory Metadata Comprehensive handbook that functions as both documentation and scholarly publication; agents can keep long-form docs, citations, and accessibility checks aligned.
One Template to Rule Them All This repository’s own presentation site, demonstrating meta-application; agents can reuse the same setup, validation, and publication workflow documented in this template.

Installation

We recommend using GitHub Codespaces for a reproducible setup.

Getting Started

Prek Git Hooks

This template uses Prek for managing Git hooks with a pre-commit-compatible configuration. To install hooks locally:

npm install
npm run prepare

To run all hooks on demand:

prek run --all-files

If Prek is not installed globally, you can run:

npx @j178/prek run --all-files

For Most Users: Reproducible Setup with GitHub Codespaces

Use this template for your project in a new repository on your GitHub account.
Click the green <> Code button at the top right of this repository.
Select the “Codespaces” tab and click “Create codespace on main”. GitHub will now build a container that includes:
- ✅ Node.js (via npm)
- ✅ Python with uv
- ✅ R with renv
- ✅ Quarto
Once the Codespace is ready, open a terminal and preview the documentation:
```
uv run quarto preview
```

Note: All dependencies (Node.js, Python, R, Quarto) are pre-installed in the Codespace.

👩‍💻 Advanced Local Installation

Prerequisites

Node.js
R and Rtools (on Windows)
uv (Python manager)
Quarto

Note: uv installs and manages the correct Python version automatically.

Local Setup Steps

# 1. Install Node.js dependencies
npm install
npm run prepare

# 2. Setup Python environment
uv sync

# 3. Setup R environment
Rscript -e 'install.packages("renv"); renv::restore()'

# 4. Preview documentation
uv run quarto preview

Project Setup

After creating your project from this template (either via Codespaces or local setup), follow the comprehensive checklist in TODO.md to customize and finalize your project. The checklist includes essential setup tasks, optional enhancements, and verification steps to ensure your research data repository is properly configured.

If you want a coding agent to help, point it to .github/copilot-instructions.md first and then ask it to work through the checklist items marked as agent-assisted.

Setup step	Typical owner	References
Replace placeholders, customize metadata, and update documentation	🤖 Agent-assisted	TODO.md, .github/copilot-instructions.md
Run formatting, changelog, preview, and validation commands	🤖 Agent-assisted	Use, .github/template-site/agent-release-workflow.qmd
Enable GitHub Security, Branch Protection, Pages, and Zenodo settings	👤 Manual in GitHub/Zenodo	TODO.md
Approve the final release and publish production artifacts	🤝 Shared: agent prepares, maintainer confirms	.github/template-site/agent-release-workflow.qmd

Use

Check that all files are properly formatted.

npm run check

Format all files with Prettier.

npm run format

Format all Python files with Ruff and lint with ty (if applicable).

uv run ruff format
uv run ruff check
uv run ty check

Format all R files with styler and lint with lintr.

styler::style_dir(".")
lintr::lint_dir(".")

Run the wizard to write meaningful commit messages.

npm run commit

For agent workflows, prefer one focused commit per logical change so git-cliff can turn the Conventional Commit subject into a short changelog line without extra cleanup. Multi-line commit messages are now truncated to their first line in changelog output, so keeping the subject specific is what matters most.

Run the wizard to draft changelog entries.

npm run changelog

For repositories created from this template, curate the result in CHANGELOG.template.md and rename it to CHANGELOG.md during finalization.

If you only need a compact preview while iterating with a coding agent, use:

npm run changelog:unreleased

If your clone is shallow, fetch the full history first so the generated changelog reflects the history you want to summarize:

git fetch --tags --unshallow origin

Preview the documentation.

quarto preview

Check for broken links in the source documentation with Lychee.

Lychee is a Rust-based CLI tool. Install it first:

macOS: brew install lychee
Linux: cargo install lychee
Other: See lychee.cli.rs

Then run the link check:

npm run lychee-check

Prepare a Zenodo-friendly site archive before creating a GitHub release.

npm run site:build
npm run site:archive -- --tag v1.0.0

Or run the combined helper, which builds the site, creates release-artifacts/site-v1.0.0.zip, and stages the archive directory for commit:

npm run release:prepare -- --tag v1.0.0
npm run commit

Commit the generated archive before you publish the GitHub release. Zenodo captures files that are already in the tagged repository snapshot, while the release workflow only mirrors the same ZIP onto the GitHub release page for convenient downloading.

If you change Quarto’s output directory from _site, pass the matching folder with --site-dir, for example npm run site:archive -- --tag v1.0.0 --site-dir site.

Support

This project is maintained by @maehr. Please understand that we can’t provide individual support via email. We also believe that help is much more valuable when it’s shared publicly, so more people can benefit from it.

Type	Platforms
🚨 Bug Reports	GitHub Issue Tracker
📊 Report bad data	GitHub Issue Tracker
📚 Docs Issue	GitHub Issue Tracker
🎁 Feature Requests	GitHub Issue Tracker
🛡 Report a security vulnerability	See SECURITY.md
💬 General Questions	GitHub Discussions

Template roadmap

v1.0.0 release readiness

Document agent-assisted setup, validation, and release preparation workflows
Ship changelog guidance that is based on commit history and ready for automation
Preserve rendered HTML documentation in tagged repository snapshots for Zenodo archival
Record the template repository’s Zenodo concept DOI and live citation metadata
Publish the first stable GitHub release for the repository

Post-v1.0.0

Expand agent recipes for project-specific metadata, showcase updates, and support tasks
Add smoke tests for preview and template customization paths
Grow the showcase gallery with more agent-assisted research data projects

Contributing

Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Authors and credits

Moritz Mähr - Initial work - maehr - ORCID
Moritz Twente - Enhancements - mtwente - ORCID

See also the list of contributors who contributed to this project.

License

The data in this repository is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) License - see the LICENSE-CCBY file for details. By using this data, you agree to give appropriate credit to the original author(s) and to indicate if any modifications have been made.

The code in this repository is released under the GNU Affero General Public License v3.0 - see the LICENSE-AGPL file for details. By using this code, you agree to make any modifications available under the same license.