PostDoc Potential Website

This is the source repository of postdoc-potential.github.io, a platform created for and by early-career researchers navigating postdoctoral research positions in Earth Sciences.

Table of Contents

• Features
• Built With
• Repository Structure
• Getting Started
• Local Development
• Updating Website
• Website Performance
• Site Creator
• Credits, License and Privacy
• Reporting an Issue

Features

The main features of our website are:

• Open-sourced survey with a Google API plugin for the data storage backend
• Direct messaging option using Web3Forms
• Direct links to team members' and collaborators' profiles
• Easily customisable layout for future additions

Built With

• Jekyll — static site generator (via the jekyll-theme-minimal base theme)
• Ruby / Bundler — Jekyll's runtime, managed via Gemfile / Gemfile.lock (see .ruby-version for the required Ruby version)
• GitHub Pages — hosting and deployment, with GitHub Actions CI (.github/workflows/ci.yml) and Dependabot for dependency updates
• HTML / SCSS / CSS — page markup and styling (_layouts/, _includes/, _sass/, assets/css/)
• JavaScript — front-end interactivity, e.g. popups and form handling (assets/js/)
• SurveyJS — used to make the survey form in /survey/ (survey.json, theme.js)
• Google Sheets/Forms API — survey data storage backend
• Web3Forms — contact / direct messaging form handling

Repository Structure

This is a Jekyll site. Key folders and files (build output in _site/ and the _archive/ folder of deprecated files are omitted for brevity):

postdoc-potential.github.io/
├── _layouts/
│   ├── default.html          # Base page layout
│   ├── feature.html
│   └──webinar.html
├── _includes/                # Reusable partials
│   ├── header.html
│   ├── footer.html
│   ├── navigation.html
│   ├── hero.html
│   ├── hero-CTA.html
│   └── popup.html
├── _sass/
│   └── jekyll-theme-minimal.scss   # Theme styling
├── _data/          
│   └── webinar.yml           # Webinar talks list, grouped by year — powers the /webinar/ index
├── assets/
│   ├── css/style.scss        # Main stylesheet — edit here for site-wide style changes
│   ├── img/                  # All images used in the site
│   │   └── webinar/           # /webinar/ index page (layout: webinar), lists talks from _data/webinar.yml
│   └── js/                   # Reusable JavaScripts
├── survey/                   # Survey page (HTML/JS/CSS + survey.json)
├── webinar.md 
|── webinar/                   # One .md file per webinar/episode page (layout: feature)
│   └── s01e01.md
├── docs/
│   └── image_workflow.md
├── scripts/exif-credits/     # Image credit/attribution files
├── .github/
│   ├── ISSUE_TEMPLATE/
│   └── workflows/ci.yml      # CI
├── _config.yml               # Jekyll site config
├── Gemfile / Gemfile.lock    # Ruby dependencies
├── .ruby-version
├── index.md
├── team.md
├── contact.html
├── credits.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── README.md

Getting Started

1. Meet the Team: Check out our Team Page to see who's contributed and shared their experiences.
2. Take our survey: Participate in our survey by sharing your experience.
3. Share Your Story: Want to collaborate or volunteer? Visit contact by sending an email or dropping a direct message.

Local Development

This site runs on Jekyll. To preview it locally:

git clone https://github.com/postDoc-potential/postdoc-potential.github.io.git
cd postdoc-potential.github.io

# Install the Ruby version specified in .ruby-version, then:
bundle install
bundle exec jekyll serve

The site will be available at http://localhost:4000. Jekyll will rebuild automatically as you edit files (run with --livereload for auto-refresh in the browser).

If you don't have Ruby/Bundler set up yet, see the GitHub Pages local Jekyll setup guide for OS-specific installation steps.

macOS setup

macOS ships with an outdated system Ruby, so install a current Ruby via Homebrew rather than using sudo gem install against the system Ruby:

# Install Homebrew first if you don't have it: https://brew.sh/
brew install ruby

# Make sure Homebrew's Ruby (not the system Ruby) is first on your PATH
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc   # Apple Silicon
# echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc   # Intel Macs
source ~/.zshrc

ruby -v      # confirm it's the Homebrew Ruby, not /usr/bin/ruby
gem install bundler jekyll

Then clone the repo and run the same bundle install / bundle exec jekyll serve commands shown above. If bundle install fails with a permissions error, it usually means the system Ruby is still first on your PATH — re-check the echo $PATH output before retrying.

Updating Website

Quick Links

Everything below is documented in full in CONTRIBUTING.md — these are the four things most contributors need first:

I want to...	Where to look
🤝 Contribute a change (setup, branching, opening a PR)	CONTRIBUTING.md
🚀 Push my changes without touching main directly	Branching Workflow
🖼️ Add or update an image (resize, metadata, WebP conversion)	Adding Images
📄 Add or update a page (including webinar pages)	Adding or Editing Content · Adding a Webinar Page

To become a contributor

Please see CONTRIBUTING.md for getting started with contributions. Make sure that you follow the CODE_OF_CONDUCT.md while contributing and engaging in discussions.

When contributing, please first discuss the change you wish to make via an issue on this repository before making the actual change.

Website Performance

Site Creator

Rituparna Sarkar

Credits, License and Privacy

For full credits and our privacy policy, read our Credits, License and Privacy Statement.

Reporting an Issue

If you experienced a bug while visiting our website, or want to recommend a feature, feel free to open an issue. Check our Security Policy for reporting a security vulnerability.