https://github.com/maehr/open-research-data-template
GitHub template for FAIR and open research data
https://github.com/maehr/open-research-data-template
fair github-pages open-data open-research-data open-science ord repository-pattern template template-repository
Last synced: 2 months ago
JSON representation
GitHub template for FAIR and open research data
- Host: GitHub
- URL: https://github.com/maehr/open-research-data-template
- Owner: maehr
- License: agpl-3.0
- Created: 2023-03-15T09:33:25.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-19T20:59:19.000Z (3 months ago)
- Last Synced: 2026-03-20T05:47:29.653Z (3 months ago)
- Topics: fair, github-pages, open-data, open-research-data, open-science, ord, repository-pattern, template, template-repository
- Language: Markdown
- Homepage: https://maehr.github.io/open-research-data-template/
- Size: 14.3 MB
- Stars: 29
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-AGPL.md
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: SECURITY.md
- Maintainers: .github/MAINTAINERS.md
- Agents: AGENTS.md
Awesome Lists containing this project
- jimsghstars - maehr/open-research-data-template - GitHub template for FAIR and open research data (Markdown)
README
# 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](https://www.go-fair.org/fair-principles/) and open science. It is independent of data type or format and implements best practices as outlined in [The Turing Way](https://book.the-turing-way.org/). Core components include automated release management, integrated archiving with [Zenodo](https://zenodo.org/), structured documentation via [Quarto](https://quarto.org/), and long-term accessibility through [GitHub Pages](https://pages.github.com/).
[](https://github.com/maehr/open-research-data-template/issues)
[](https://github.com/maehr/open-research-data-template/network)
[](https://github.com/maehr/open-research-data-template/stargazers)
[](https://github.com/maehr/open-research-data-template/blob/main/LICENSE-AGPL.md)
[](https://github.com/maehr/open-research-data-template/blob/main/LICENSE-CCBY.md)
[](https://doi.org/10.5281/zenodo.19111355)
> [!IMPORTANT]
> This `README.md` describes the **template repository itself**. If you created a new repository from this template, start with [TODO.md](TODO.md), then customize the project-facing template files: [CITATION.template.cff](CITATION.template.cff), [CODE_OF_CONDUCT.template.md](CODE_OF_CONDUCT.template.md), [SECURITY.template.md](SECURITY.template.md), [README.template.md](README.template.md), and [CHANGELOG.template.md](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](https://dh-tech.github.io/2025/06/04/digital-humanities-tech-symposium-agenda/) 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/](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](https://doi.org/10.5281/zenodo.19111355), the live [CITATION.cff](CITATION.cff), and the downstream [CITATION.template.cff](CITATION.template.cff)
- Automatic long-term archiving with [Zenodo](https://zenodo.org/), plus a commit-ready rendered site archive for tagged snapshots
- Licensed under [AGPL 3.0](https://www.gnu.org/licenses/agpl-3.0.html) and [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed) according to [The Turing Way](https://book.the-turing-way.org/reproducible-research/rdm/rdm-sharing.html#step-3-choose-a-licence-and-link-to-your-paper-and-code)
- Template for reporting data issues via `github/ISSUE_TEMPLATE/data_issue_report.yml`
### Documentation
- `README.md` following [www.makeareadme.com](https://www.makeareadme.com/) and [The Turing Way](https://book.the-turing-way.org/project-design/pd-overview/project-repo/project-repo-readme)
- `CHANGELOG.md` for template release notes and `CHANGELOG.template.md` as the downstream project scaffold
- Automated changelog generation with [git-cliff](https://github.com/orhun/git-cliff)
- Machine-readable project metadata in `package.json` with [npm](https://docs.npmjs.com/cli/v7/configuring-npm/package-json)
- Accessible documentation with [GitHub Pages](https://docs.github.com/en/pages) and [Quarto](https://quarto.org/)
### Consistency
- Code formatting with [Prettier](https://prettier.io/) for general files, [Ruff](https://github.com/astral-sh/ruff) for Python, and [styler](https://styler.r-lib.org/) and [lintr](https://lintr.r-lib.org/) for R
- Python type checking with [ty](https://github.com/astral-sh/ty)
- Python dependency management with [uv](https://github.com/astral-sh/uv)
- R dependency management with [renv](https://rstudio.github.io/renv/)
- Commit messages following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) enforced via [prek](https://prek.j178.dev/)
- Versioning following [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
- Workflow based on [fork and pull](https://gist.github.com/Chaser324/ce0505fbed06b947d962) with [GitHub branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule)
- Issue tracking via [issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
- File and folder naming conventions following [The Turing Way](https://book.the-turing-way.org/project-design/info-management/filenaming/)
### Security
- `SECURITY.md` following [GitHub guidelines](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository), with `SECURITY.template.md` for downstream projects
- Vulnerability monitoring with [GitHub Security Alerts](https://github.blog/2017-11-16-introducing-security-alerts-on-github/)
- Repository integrity enforced via [GitHub branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule)
### Ethics
- `CODE_OF_CONDUCT.md` following the [Contributor Covenant](https://www.contributor-covenant.org/), 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"](https://maehr.github.io/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**](https://dokumentation.stadtgeschichtebasel.ch/)
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**](https://dokumentation.stadtgeschichtebasel.ch/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**](http://mtwente.github.io/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**](https://mtwente.github.io/maxvogt-analysis/)
Multi-step data compilation workflow documentation; agents can keep processing notes, metadata edits, and changelog updates aligned across the pipeline. | 
|
| [**Modelling Marti**](https://mtwente.github.io/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**](https://digihistch24.github.io/)
Conference website with program, abstracts, and participant information; agents can batch-edit schedules, validate links, and keep publication assets consistent. | 
|
| [**Digital Humanities Bern**](https://dhbern.github.io/)
Department hub featuring news, events, and course information; agents can maintain navigation, announcement pages, and formatting checks for multi-page sites. | 
|
| [**Decoding Inequality 2025**](https://dhbern.github.io/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**](https://maehr.github.io/diskriminierungsfreie-metadaten/)
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**](https://maehr.github.io/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](https://github.com/features/codespaces)** for a reproducible setup.
## Getting Started
### Prek Git Hooks
This template uses [Prek](https://prek.j178.dev/) for managing Git hooks with a pre-commit-compatible configuration. To install hooks locally:
```bash
npm install
npm run prepare
```
To run all hooks on demand:
```bash
prek run --all-files
```
If Prek is not installed globally, you can run:
```bash
npx @j178/prek run --all-files
```
### For Most Users: Reproducible Setup with GitHub Codespaces
1. **[Use this template](https://github.com/new?template_name=open-research-data-template&template_owner=maehr)** for your project in a new repository on your GitHub account.
2. Click the green **`<> Code`** button at the top right of this repository.
3. 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
4. Once the Codespace is ready, open a terminal and preview the documentation:
```bash
uv run quarto preview
```
> **Note:** All dependencies (Node.js, Python, R, Quarto) are pre-installed in the Codespace.
👩💻 Advanced Local Installation
#### Prerequisites
- [Node.js](https://nodejs.org/en/download/)
- [R](https://cran.r-project.org/) and Rtools (on Windows)
- [uv (Python manager)](https://github.com/astral-sh/uv#installation)
- [Quarto](https://quarto.org/docs/get-started/)
> _Note: `uv` installs and manages the correct Python version automatically._
#### Local Setup Steps
```bash
# 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](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](.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](TODO.md), [.github/copilot-instructions.md](.github/copilot-instructions.md) |
| Run formatting, changelog, preview, and validation commands | 🤖 Agent-assisted | [Use](#use), [.github/template-site/agent-release-workflow.qmd](.github/template-site/agent-release-workflow.qmd) |
| Enable GitHub Security, Branch Protection, Pages, and Zenodo settings | 👤 Manual in GitHub/Zenodo | [TODO.md](TODO.md) |
| Approve the final release and publish production artifacts | 🤝 Shared: agent prepares, maintainer confirms | [.github/template-site/agent-release-workflow.qmd](.github/template-site/agent-release-workflow.qmd) |
## Use
Check that all files are properly formatted.
```bash
npm run check
```
Format all files with [Prettier](https://prettier.io/).
```bash
npm run format
```
Format all Python files with [Ruff](https://github.com/astral-sh/ruff) and lint with [ty](https://github.com/astral-sh/ty) (if applicable).
```bash
uv run ruff format
uv run ruff check
uv run ty check
```
Format all R files with [styler](https://styler.r-lib.org/) and lint with [lintr](https://lintr.r-lib.org/).
```r
styler::style_dir(".")
lintr::lint_dir(".")
```
Run the wizard to write meaningful commit messages.
```bash
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.
```bash
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:
```bash
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:
```bash
git fetch --tags --unshallow origin
```
Preview the documentation.
```bash
quarto preview
```
Check for broken links in the source documentation with [Lychee](https://lychee.cli.rs/).
Lychee is a Rust-based CLI tool. Install it first:
- macOS: `brew install lychee`
- Linux: `cargo install lychee`
- Other: See [lychee.cli.rs](https://lychee.cli.rs/)
Then run the link check:
```bash
npm run lychee-check
```
Prepare a Zenodo-friendly site archive before creating a GitHub release.
```bash
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:
```bash
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](https://github.com/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](https://github.com/maehr/open-research-data-template/issues) |
| 📊 **Report bad data** | [GitHub Issue Tracker](https://github.com/maehr/open-research-data-template/issues) |
| 📚 **Docs Issue** | [GitHub Issue Tracker](https://github.com/maehr/open-research-data-template/issues) |
| 🎁 **Feature Requests** | [GitHub Issue Tracker](https://github.com/maehr/open-research-data-template/issues) |
| 🛡 **Report a security vulnerability** | See [SECURITY.md](SECURITY.md) |
| 💬 **General Questions** | [GitHub Discussions](https://github.com/maehr/open-research-data-template/discussions) |
## Template roadmap
### v1.0.0 release readiness
- [x] Document agent-assisted setup, validation, and release preparation workflows
- [x] Ship changelog guidance that is based on commit history and ready for automation
- [x] Preserve rendered HTML documentation in tagged repository snapshots for Zenodo archival
- [x] 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](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](https://github.com/maehr) - [ORCID](https://orcid.org/0000-0002-1367-1618)
- **Moritz Twente** - _Enhancements_ - [mtwente](https://github.com/mtwente) - [ORCID](https://orcid.org/0009-0005-7187-9774)
See also the list of [contributors](https://github.com/maehr/open-research-data-template/graphs/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](LICENSE-CCBY.md) 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](LICENSE-AGPL.md) file for details. By using this code, you agree to make any modifications available under the same license.