Development Setup

This page documents the local installations and repository settings needed to build, preview, and deploy the Just the Docs site.

Required Tools

  • Git
  • Ruby 3.3
  • Bundler
  • Jekyll, installed through the repository Gemfile
  • A C/C++ build toolchain for native Ruby gems
  • Optional: R, if you want to run scripts/simulate_ehr_data.R

Do not rely on a global Jekyll executable. This repository pins Jekyll and the Just the Docs theme through Bundler.

macOS Installation

Install Ruby 3.3 with Homebrew:

brew install ruby@3.3

Add Ruby 3.3 to your shell path:

export PATH="/opt/homebrew/opt/ruby@3.3/bin:$PATH"

Confirm the expected Ruby version:

ruby -v

Install the project dependencies from the repository root:

bundle install

Linux Installation

Install Ruby 3.3 and build tools using your system package manager or a Ruby version manager such as rbenv. Then install dependencies from the repository root:

bundle install

The GitHub Pages workflow uses ruby/setup-ruby with Ruby 3.3, so local Ruby 3.3 is the closest match to CI.

Conda And Miniforge Notes

If Conda or Miniforge sets compiler variables, native Ruby gem installation can fail. In that case, run Bundler or Jekyll with those variables unset:

env -u CC -u CXX -u LD -u LDFLAGS -u CPPFLAGS -u CFLAGS PATH=/opt/homebrew/opt/ruby@3.3/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin bundle install

Use the same pattern for builds:

env -u CC -u CXX -u LD -u LDFLAGS -u CPPFLAGS -u CFLAGS PATH=/opt/homebrew/opt/ruby@3.3/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin bundle exec jekyll build

Local Build

Build the static site:

bundle exec jekyll build

Preview the site locally:

bundle exec jekyll serve --host 127.0.0.1 --port 4000

With the configured base URL, the local preview is available at:

http://127.0.0.1:4000/practical-genai-coding-guide/

GitHub Pages Deployment

The repository is configured to deploy from GitHub Actions through .github/workflows/pages.yml.

The workflow:

  • Checks out the repository.
  • Uses Ruby 3.3.
  • Installs gems through Bundler cache.
  • Builds the site with bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}".
  • Uploads the generated site artifact.
  • Deploys to GitHub Pages.

Repository settings must use GitHub Actions as the Pages source:

  1. Open the repository on GitHub.
  2. Go to Settings > Pages.
  3. Set Build and deployment > Source to GitHub Actions.
  4. Push to main or run the Pages workflow manually.

Expected public URL:

https://fritschelab.org/practical-genai-coding-guide/

Lab domain

The lab’s organization site uses fritschelab.org. GitHub Pages project sites inherit that domain unless they have their own custom domain, so this guide keeps baseurl: "/practical-genai-coding-guide" and uses url: "https://fritschelab.org". The previous fritschelab.github.io/practical-genai-coding-guide/ address redirected to the new HTTPS address when checked September 5, 2026.

Manage the apex domain on the lab’s organization site and its DNS provider. Do not add a guide-specific CNAME for this path: a custom-domain setting is a hostname, not a hostname plus /practical-genai-coding-guide/. See GitHub’s documentation on sharing a custom domain across repositories. Local preview still uses the same path on 127.0.0.1.

Optional R Setup

The documentation site does not require R. R is needed to run the synthetic EHR data script or adapt the R code skeleton.

Install R, then prepare dependencies before running an analysis. This repository does not ship a renv.lock. For a plain R project, install the simulator’s dependency explicitly:

Rscript -e 'install.packages("optparse", repos = "https://cloud.r-project.org")'
Rscript scripts/simulate_ehr_data.R --help

The R code skeleton uses both optparse and readr by default. Install those before adapting it:

Rscript -e 'install.packages(c("optparse", "readr"), repos = "https://cloud.r-project.org")'

If your working project already has a renv.lock, follow its setup instructions and run renv::restore() from the project root to restore the recorded dependencies instead of selecting current package versions. See the renv introduction. Both R files report missing packages and stop; they do not install packages during execution.

The simulator’s demographic age is a snapshot as of December 31, 2019, and some measurements can be from before a person’s 20th birthday. The advanced BMI exercise uses age at measurement calculated from birth and measurement dates when restricting records to ages 20 and older.

Troubleshooting

  • jekyll: command not found: run Jekyll through Bundler with bundle exec jekyll build.
  • Ruby version mismatch: confirm that ruby -v reports Ruby 3.3 and that your shell path points to the intended Ruby.
  • Native gem compilation failures: unset Conda or Miniforge compiler variables as shown above.
  • Site builds but links look wrong locally: use the configured base URL path, /practical-genai-coding-guide/.
  • GitHub Pages does not deploy: confirm the Pages source is set to GitHub Actions and inspect the Deploy Jekyll site to Pages workflow logs.