Gerard Martí Juan

Local development

Local development

This guide serves the branch that is currently checked out. It works for master, a remote feature branch, a local feature branch, or a checkout with uncommitted edits. Serving a branch locally never deploys it to GitHub Pages.

Choose the branch

From the repository root:

git fetch --prune origin
git branch --all
git status --short --branch

Switch to an existing local branch with:

git switch <branch-name>

Create a local tracking branch from a remote branch the first time:

git switch --track origin/<branch-name>

Do not switch branches while you have edits that belong to the current branch. Review git status first; commit, copy, or stash those edits intentionally. Do not use git reset --hard as a way to make branch switching work.

The server reads the files in the current checkout, including uncommitted changes. Confirm the branch and commit in a second terminal before sharing a preview:

git branch --show-current
git log -1 --oneline --decorate

Install the toolchain

The repository targets Ruby 3.2.2, declared in .ruby-version, and Jekyll comes from the github-pages dependency in Gemfile. The repository does not track Gemfile.lock, so Bundler may resolve platform-specific patch versions on a fresh machine.

macOS with rbenv

Install rbenv and its Ruby build plugin once if they are not already available:

brew install rbenv ruby-build

Then install/select the repository’s Ruby and run the commands through it:

rbenv install 3.2.2             # only if this version is not installed
rbenv local 3.2.2
gem install bundler -v 2.4.10    # only if this Bundler version is missing
rbenv exec bundle install

rbenv exec avoids accidentally using the system Ruby. The repository’s .bundle/ and vendor/ directories are local-only and ignored by Git.

The lightweight Python validation helpers use uv. Install it once if it is not already available:

brew install uv

GitHub Codespaces or the dev container

The checked-in .devcontainer/devcontainer.json uses the Jekyll dev-container image, forwards port 4000, and runs bundle install after creation. Open the repository in a Codespace, wait for the post-create install to finish, and use bundle directly. The commands below use rbenv exec for macOS; in a Codespace or dev container, remove that prefix.

Serve the current branch

Install dependencies once, then start Jekyll with live reload:

rbenv exec bundle install
rbenv exec bundle exec jekyll serve --livereload --host 127.0.0.1 --port 4000

In a Codespace or dev container, use the same command without the rbenv prefix, and listen on all container interfaces so the forwarded port works:

bundle exec jekyll serve --livereload --host 0.0.0.0 --port 4000

Open http://127.0.0.1:4000/. Edit the checked-out files and refresh when the browser reloads. Stop the server with Ctrl-C.

If port 4000 is already in use, choose another port without changing the site configuration:

rbenv exec bundle exec jekyll serve --livereload --host 127.0.0.1 --port 4001

Preview multiple branches at once

Use separate Git worktrees so each preview has its own branch and files:

git worktree add ../GerardMJuan-site-<branch-slug> <branch-name>
cd ../GerardMJuan-site-<branch-slug>
rbenv exec bundle install
rbenv exec bundle exec jekyll serve --livereload --host 127.0.0.1 --port 4001

Use a different port for each worktree. Remove a worktree only after its server is stopped and its changes are no longer needed:

git worktree remove ../GerardMJuan-site-<branch-slug>

Validate before sharing or merging

These checks match the repository’s build and CI expectations:

uv run --no-project scripts/test_import_bibtex.py
rbenv exec bundle exec jekyll doctor
rbenv exec bundle exec jekyll build --trace
uv run --no-project scripts/validate_site.py --site ./_site
git diff --check

In a Codespace or dev container, remove rbenv exec from the two Bundler commands.

The validator checks source JSON, chart references, Mermaid blocks, generated HTML, local links, duplicate IDs, image alt text, and generated search JSON. The generated _site/ directory is ignored and should not be committed.

For content changes, inspect the rendered page as well as the command output. Publication entries in _data/publications.yml are factual content: verify the title, author list, venue, year, page or article number, DOI, and research topic against an authoritative source before merging. A passing build cannot verify those facts.

CI/CD boundary

Pull requests targeting master or main build and validate the site but do not deploy it. A push to the default branch runs the GitHub Pages deployment. A branch without a pull request does not receive a GitHub Actions build under the current workflow, so run the local checks above before sharing its preview.

Troubleshooting

  • Bundler uses the wrong Ruby: use rbenv exec bundle ...; confirm with rbenv version and ruby --version.
  • Port binding is denied in a restricted agent environment: run the static doctor, build, and validator commands instead, or use the host’s normal terminal/browser environment for a live preview.
  • A branch switch is blocked by local edits: stop and inspect git status. Preserve the edits intentionally; do not discard them with a destructive reset.
  • A link works in the source but fails in validation: inspect the generated _site/ path, because Jekyll permalink and relative-link behavior is what visitors receive.