Paper Plain: Science, Deciphered

A minimalist, high-fidelity research blog that translates complex research papers into plain English. Built with Quarto, Python, and GitHub Actions.

Overview

This project is a digital library of summary reports based on select Open Access research papers. Each report features:

• Plain English Summaries: High-level takeaways without the academic gatekeeping.

• Jargon Decoder: An automated system that pulls definitions from a report-specific jargon.csv file.

• Interactive References: Full BibTeX integration for academic traceability.

Tech Stack

• Engine: Quarto (Markdown-based publishing)
• Language: Python 3.10+ (for data handling and table generation)
• Environment: Conda / Micromamba
• Deployment: GitHub Pages via GitHub Actions

Project Structure

├── reports/
│   ├── _template/          # Boilerplate for new reports
│   └── [report-name]/
│       ├── index.qmd       # Main report content
│       ├── jargon.csv      # Terminology for the paper
│       ├── references.bib  # Citations for the paper
│       └── images/         # Local figures and teasers
├── assets/                 # Global icons, logos, and custom CSS
├── _jargon-decoder.qmd     # Custom component to render jargon decoder table
├── _quarto.yml             # Global site configuration
└── environment.yml         # Conda environment definition

Local Development

1. Prerequisites Ensure you have Quarto installed on your machine.

2. Setup Environment This project uses Conda/Micromamba to manage Python dependencies (pandas, tabulate, ipykernel).

Create the environment:

conda env create -f environment.yml

Activate the environment:

conda activate paper-plain

3. Previewing the Site To launch a live local preview that updates as you edit:

quarto preview

4. Adding a New Report

• Duplicate the Template inside the reports/_template folder.
• Update Metadata in index.qmd.
• Fill the jargon.csv file with terms and definitons specific to the paper.
• Add the BibTeX entries to the references.bib.
• Write the "Plain English" summary sections.
• The Jargon Decoder sectoin will automatically render a table based on the jargon.csv file.

Automated Deployment

This site uses GitHub Actions to automatically render and publish content.

On every push to main, the .github/workflows/publish.yml workflow:

1. Sets up the Micromamba environment.
2. Renders all .qmd files.
3. Deploys the static site to the gh-pages branch.