Welcome to the definitive guide on installing MEEP (MIT Electromagnetic Equation Propagation) on Arch Linux. If you are venturing into the world of computational photonics, you’ve likely encountered MEEP. It is a powerful, open-source finite-difference time-domain (FDTD) simulation software used extensively for modeling electromagnetic waves, photonic crystals, waveguides, and metamaterials.

However, compiling MEEP from source on Arch Linux can be a daunting task filled with dependency hell. The most robust, stable, and user-friendly way to install MEEP is by leveraging Conda, specifically through Miniforge.

In this professional guide, we will walk you through a pristine setup, covering:

• Installing Miniforge (the optimal Conda distribution).
• Creating an isolated Conda environment for MEEP.
• Installing PyMeep alongside the scientific Python stack.
• Integrating your environment seamlessly with Jupyter and VS Code.
• Running a robust verification FDTD simulation to guarantee everything works flawlessly.

Let’s dive in!

1. Why Miniforge and Conda?

Arch Linux is a rolling release distribution, meaning system packages are constantly updated. MEEP relies on heavily compiled libraries (like HDF5, NumPy, and SciPy) that can easily break during a system update if built from source.

By using Conda, we create an isolated environment that locks down dependencies, ensuring your scientific work remains stable. We specifically recommend Miniforge over Anaconda or Miniconda because:

• It defaults to the conda-forge channel, which is community-maintained and has the most up-to-date MEEP binaries.
• It avoids the commercial licensing restrictions recently introduced by Anaconda.
• It is lightweight and doesn’t bloat your system with unnecessary packages.

Here is the architecture we are building:

1
2
3
4
5
6
Arch Linux System
    └── Miniforge (Conda)
            └── "meep" Environment
                    ├── pymeep
                    ├── numpy, scipy, matplotlib
                    └── jupyter, ipykernel

2. Preparing Your System

Before installing Miniforge, let’s verify a few system parameters to ensure we download the correct binaries.

Check your system architecture

Open your terminal and run:

1
uname -m

You should see x86_64 for a standard 64-bit Intel or AMD machine. Miniforge provides specific installers based on this architecture.

Verify your default shell

Conda needs to initialize itself by modifying your shell configuration file (e.g., ~/.bashrc or ~/.zshrc). Check your active shell:

1
echo $SHELL

If the output is /usr/bin/bash, you are using Bash. If you use Zsh, keep that in mind, as Conda will update your .zshrc instead.

3. Installing Miniforge

Let’s download and install Miniforge to handle our MEEP dependencies.

Download the Installer

Use curl to pull the latest Linux x86-64 installer script directly from GitHub:

1
curl -L -o ~/miniforge.sh https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh

Execute the Installer

Run the script using Bash:

1
bash ~/miniforge.sh

During the installation, you will be prompted with several questions:

1. License Agreement: Press Enter to read, and type yes to accept.
2. Installation Directory: Press Enter to accept the default location (usually ~/miniforge3).
3. Conda Initialization (Crucial): When asked Do you wish the installer to initialize Miniforge3 by running conda init?, type yes. This ensures Conda is loaded every time you open a terminal.

Reload Your Shell

To apply the changes without restarting your terminal, source your configuration file:

1
source ~/.bashrc

(Note: Use source ~/.zshrc if you are on Zsh).

You should now see (base) prefixed to your terminal prompt, indicating that Conda is active.

Verify the installation:

1
conda --version

Expected Output: conda 26.x.x (or similar).

4. Configuring Conda-Forge

Miniforge comes with conda-forge configured by default, but it is best practice to explicitly enforce strict channel priority. This prevents Conda from mixing packages from different channels, which can lead to broken environments.

1
2
conda config --add channels conda-forge
conda config --set channel_priority strict

5. Setting Up the MEEP Environment

Now, we will create a completely isolated environment specifically for MEEP. We will name this environment meep.

1
conda create -n meep pymeep

When prompted with Proceed ([y]/n)?, type y and press Enter. Conda will automatically resolve and download the pre-compiled PyMeep package along with its complex C++ dependencies.

Once finished, activate your new environment:

1
conda activate meep

Your prompt will change from (base) to (meep), confirming you are inside the isolated sandbox.

6. Verifying the Core Installation

Before adding more tools, let’s ensure PyMeep installed correctly and can communicate with Python.

Run the following command:

1
python -c "import meep as mp; print('MEEP Version:', mp.__version__); print('Vector Test:', mp.Vector3(1, 2, 3))"

Expected Output:

1
2
MEEP Version: 1.34.0
Vector Test: Vector3<1.0, 2.0, 3.0>

(Your version number may vary slightly).

If you see this output, congratulations! The hardest part is over. MEEP is successfully installed on your Arch Linux machine.

7. Installing the Scientific Stack & Jupyter

MEEP simulations are rarely run in isolation. You will need NumPy for array manipulation, Matplotlib for visualizing electromagnetic fields, and Jupyter for interactive development.

Install the standard scientific stack inside your meep environment:

1
conda install numpy scipy matplotlib jupyter ipykernel h5py autograd

Registering the Jupyter Kernel

To ensure Jupyter Notebooks and VS Code can “see” your MEEP environment, you must register it as a kernel.

Run this command while the meep environment is active:

1
python -m ipykernel install --user --name meep --display-name "Python (Meep)"

This tells Jupyter: “Here is a Python environment called ‘Python (Meep)’. Make it available in the UI.”

Verify the kernel registration:

1
jupyter kernelspec list

You should see meep listed among the available kernels.

8. Integrating MEEP with VS Code

VS Code is the industry standard for Python development, offering excellent Jupyter Notebook integration.

1. Install Extensions: Open VS Code and ensure you have the Python and Jupyter extensions installed from Microsoft.
2. Create a Notebook: Create a new file named simulation.ipynb.
3. Select the Kernel: In the top right corner of the notebook interface, click Select Kernel -> Jupyter Kernel -> Python (Meep).

To absolutely confirm VS Code is using the correct environment, run this inside a notebook cell:

1
2
import sys
print(sys.executable)

The output should point to your Miniforge directory: /home/your_username/miniforge3/envs/meep/bin/python.

9. Your First FDTD Simulation

To truly prove the system is fully operational, let’s run a complete 2D FDTD simulation. This script creates a computational cell, defines a Gaussian electromagnetic pulse, runs the simulation, and visualizes the resulting Electric Field (Ez).

Copy this code into your Jupyter Notebook and run it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
import meep as mp
import numpy as np
import matplotlib.pyplot as plt

# 1. Define the computational cell and resolution
resolution = 10
cell = mp.Vector3(8, 4, 0)

# 2. Setup a Gaussian source (pulse)
sources = [
    mp.Source(
        src=mp.GaussianSource(frequency=1.0, fwidth=0.4),
        component=mp.Ez,
        center=mp.Vector3(-3, 0),
        size=mp.Vector3(0, 3)
    )
]

# 3. Initialize the simulation with Perfectly Matched Layers (PML)
sim = mp.Simulation(
    cell_size=cell,
    boundary_layers=[mp.PML(1.0)],
    sources=sources,
    resolution=resolution,
    dimensions=2
)

# 4. Run the simulation
sim.run(until=30)

# 5. Extract the Ez field data
ez = sim.get_array(
    component=mp.Ez,
    center=mp.Vector3(),
    size=cell
)

# 6. Visualize the results
plt.figure(figsize=(10, 5))
plt.imshow(
    np.transpose(ez),
    interpolation="spline36",
    cmap="RdBu",
    origin="lower"
)
plt.colorbar(label="Electric Field (Ez)")
plt.title("2D FDTD Simulation: Electromagnetic Pulse Propagation")
plt.xlabel("X Grid")
plt.ylabel("Y Grid")
plt.show()

If everything is set up correctly, a beautiful plot showing the wave propagation will appear. This validates that the MEEP solver, time-stepping, boundary conditions, and matplotlib visualization are all working in harmony!

10. Troubleshooting Common Issues

Even with a perfect guide, things can sometimes go awry. Here are the most common hiccups and how to fix them:

Error: conda: command not found

• Solution: You forgot to initialize Conda or source your shell. Run source ~/.bashrc or restart your terminal.

Error: ModuleNotFoundError: No module named 'meep'

• Solution: You are using the wrong Python interpreter. Ensure your meep environment is active (conda activate meep) in the terminal, or that you have selected the Python (Meep) kernel in VS Code.

Error: MEEP kernel doesn’t show up in VS Code

• Solution: Reload the VS Code window (Ctrl + Shift + P -> Developer: Reload Window) or re-run the ipykernel install command from step 7.

Conclusion

By using Miniforge on Arch Linux, you bypass the notorious complexities of compiling C++ electromagnetics libraries from source. You now have a robust, isolated, and highly professional scientific computing environment.

Your workflow is now streamlined:

1. Open terminal -> conda activate meep.
2. Launch VS Code -> Select Python (Meep) kernel.
3. Start simulating the photonics of the future!

Happy simulating!

This presentation provides a comprehensive overview of metalens design, functionality, and applications in modern optics research.

Download the Presentation

You can download the full presentation slide below:

📥 Download Metalens Presentation PDF

Overview

This slide deck covers:

• Fundamentals of metalens design
• Phase profile engineering
• Meta-atom structures and libraries
• Electromagnetic simulations (FDTD, RCWA)
• Performance metrics and optimization
• Practical applications

Feel free to use this presentation for research discussions, seminars, or educational purposes.

However, when we attempt to translate these continuous partial differential equations into a computer algorithm to solve complex real-world problems—such as optical wave propagation, antenna design, or computational metaoptics—we immediately hit a major mathematical roadblock: a circular recursive loop.

In this post, we will explore:

1. Maxwell’s curl equations and the need for numerical discretization.
2. The fundamental coupling paradox (the “chicken-and-egg” problem of $\mathbf{E}$ and $\mathbf{H}$).
3. How Kane S. Yee (1966) elegantly resolved this issue using space-time staggering—giving birth to the Finite-Difference Time-Domain (FDTD) method.
4. A complete mathematical explanation of the Yee Grid and the Leapfrog Algorithm.

1. Maxwell’s Curl Equations: The Continuous World

In source-free, isotropic, non-magnetic, and non-conductive media, electrodynamics is governed by Maxwell’s two curl equations:

where:

• $\mathbf{E}$ is the electric field vector $[V/m]$.
• $\mathbf{H}$ is the magnetic field vector $[A/m]$.
• $\varepsilon$ is the electric permittivity $[F/m]$.
• $\mu$ is the magnetic permeability $[H/m]$.

To make the physics crystal-clear without getting lost in 3D vector components, let’s restrict ourselves to a 1D transverse electromagnetic wave (TEM) traveling along the $x$-axis. Suppose the electric field is polarized along $y$ ($E_y$) and the magnetic field is polarized along $z$ ($H_z$).

The continuous 1D partial differential equations simplify to:

Notice the fundamental coupling here:

• The time derivative (rate of change) of $H_z$ depends on the spatial gradient of $E_y$.
• The time derivative (rate of change) of $E_y$ depends on the spatial gradient of $H_z$.

2. The Naive Discretization Dilemma: An Infinite Recursive Loop

To solve these differential equations on a digital computer, we must discretize both continuous space $x$ and continuous time $t$ into a discrete grid:

where $\Delta x$ is the spatial step size and $\Delta t$ is the time step size.

The Naive Grid Approach

What if we evaluate both $E_y$ and $H_z$ at the exact same spatial nodes $x_i = i\Delta x$ and the exact same temporal steps $t_n = n\Delta t$?

Using standard forward or central finite differences to step forward in time from step $n$ to step $n+1$:

Now ask yourself: At what time step should we compute the spatial derivatives $\frac{\partial H_z}{\partial x}$ and $\frac{\partial E_y}{\partial x}$?

• If we evaluate the spatial derivative of $H_z$ at the current time step $n$, the numerical algorithm becomes unstable.
• If we evaluate the spatial derivative at the next time step $n+1$ (to ensure stability via an implicit scheme):
  • To calculate $E_y^{n+1}(i)$, we need $H_z^{n+1}(i+1)$ and $H_z^{n+1}(i-1)$.
  • But to know $H_z^{n+1}$, we need $E_y^{n+1}(i+1)$ and $E_y^{n+1}(i-1)$!

The Circular Trap

We fall into an infinite recursive loop:

“To know $E$ at the new time, we must already know $B$ (or $H$) at the new time. But to know $B$ (or $H$) at the new time, we must already know $E$ at the new time.”

In numerical analysis, this implies that $E$ and $H$ are simultaneously coupled. You cannot solve for one explicitly without solving a massive system of linear equations across the entire grid at every single time step. This is computationally expensive, memory-intensive, and defeats the goal of a fast, local wave simulator.

3. Kane Yee’s Breakthrough: The Yee Grid & Leapfrog Scheme

In 1966, Kane S. Yee published a landmark paper that solved this fundamental circular dependency with a stroke of genius.

Yee realized that $\mathbf{E}$ and $\mathbf{H}$ should neither exist at the same place in space nor at the same moment in time!

Instead, he proposed staggering the fields in both space and time by half-step intervals ($\Delta x / 2$ and $\Delta t / 2$).

1
2
3
4
5
6
7
        Time Stepping (Leapfrog Scheme)

  E(n-1)         E(n)          E(n+1)        ... [t = n*dt]
    |              |              |
----+--------------+--------------+------> Time (t)
          |              |
       H(n-1/2)       H(n+1/2)               ... [t = (n+1/2)*dt]

1. Temporal Staggering (Leapfrog in Time)

• Electric fields $\mathbf{E}$ are defined at integer time steps: $t = n \Delta t$.
• Magnetic fields $\mathbf{H}$ are defined at half-integer time steps: $t = (n + 1/2) \Delta t$.

2. Spatial Staggering (The Yee Cell in Space)

In 1D space:

• Electric field components $E_y$ are placed at integer grid nodes: $x = i \Delta x$.
• Magnetic field components $H_z$ are placed at half-integer grid nodes: $x = (i + 1/2) \Delta x$.

1
2
3
4
5
6
7
        1D Spatial Grid Staggering

  E_y(i-1)       E_y(i)        E_y(i+1)      ... [x = i*dx]
    |              |              |
----+--------------+--------------+------> Position (x)
          |              |
      H_z(i-1/2)     H_z(i+1/2)              ... [x = (i+1/2)*dx]

4. How Space-Time Staggering Escapes the Recursive Loop

With the Yee discretization, let’s write out the finite-difference approximations for our 1D Maxwell curl equations.

Step 1: Updating $H_z$ at Half-Time Steps $(n + 1/2)$

Faraday’s law $\frac{\partial H_z}{\partial t} = -\frac{1}{\mu} \frac{\partial E_y}{\partial x}$ is evaluated at position $(i+1/2)$ and time $n$:

Rearranging to solve explicitly for $H_z^{n+1/2}$:

Look closely at the right-hand side:

• $H_z^{n-1/2}$ was calculated in the previous half time-step.
• $E_y^n(i+1)$ and $E_y^n(i)$ were calculated in the previous full time-step.

Everything on the right-hand side is already known! No matrix inversion, no unknown terms, no circular loop!

Step 2: Updating $E_y$ at Full-Time Steps $(n + 1)$

Ampère’s law $\frac{\partial E_y}{\partial t} = -\frac{1}{\varepsilon} \frac{\partial H_z}{\partial x}$ is evaluated at position $i$ and time $(n+1/2)$:

Rearranging to solve explicitly for $E_y^{n+1}$:

Look closely again:

• $E_y^n(i)$ is the current electric field.
• $H_z^{n+1/2}(i+1/2)$ and $H_z^{n+1/2}(i-1/2)$ were just computed in Step 1!

Once again, all terms on the right-hand side are known.

5. The Leapfrog Execution Loop

Because of this half-step spatial and temporal separation, the simulation execution simply “leapfrogs” back and forth endlessly:

graph TD
    A[Start: Initial E^0 and H^-1/2] --> B[Compute spatial derivative of E^n]
    B --> C[Update H^n+1/2 explicitly]
    C --> D[Compute spatial derivative of H^n+1/2]
    D --> E[Update E^n+1 explicitly]
    E --> F[Increment time step n = n + 1]
    F --> B

The infinite recursive loop is completely broken! We transformed a coupled system of continuous partial differential equations into a purely explicit, march-in-time sequence of simple arithmetic operations.

6. Why the Yee Grid is a Masterpiece of Physics

Beyond breaking the circular dependency, Yee’s spatial grid topology offers mathematical and physical properties that make it uniquely powerful:

1. Second-Order Accuracy ($\mathcal{O}(\Delta x^2, \Delta t^2)$): Because central differences are taken across half-steps ($\pm \Delta x / 2$ and $\pm \Delta t / 2$), error terms cancel out symmetrically, giving 2nd-order accuracy without needing higher-order grid stencils.

2. Divergence-Free Conditions (Implicit Gauss’s Laws): In source-free regions, Gauss’s laws state that $\nabla \cdot \mathbf{B} = 0$ and $\nabla \cdot \mathbf{D} = 0$. On the Yee grid, the curl of a curl automatically enforces zero divergence at every interior point. Gauss’s laws are satisfied implicitly by construction without needing dedicated divergence solvers!

3. Natural Geometric Match for Faraday and Ampère Loops: In 3D, electric field components lie along cell edges, while magnetic field components pass through cell faces. The line integral of $\mathbf{E}$ around a face gives the magnetic flux through that face (Faraday’s Law), and vice versa for $\mathbf{H}$ (Ampère’s Law).

7. Python Demonstration: 1D FDTD Simulation

Here is a minimal 1D Python script demonstrating the Yee leapfrog algorithm propagating a Gaussian pulse through vacuum:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import numpy as np
import matplotlib.pyplot as plt

# Physical Constants
c0 = 3.0e8      # Speed of light (m/s)
mu0 = 4.0e-7 * np.pi
eps0 = 1.0 / (c0**2 * mu0)

# Grid Parameters
Nx = 200        # Number of spatial cells
dx = 1e-3       # Spatial step (1 mm)
Courant = 0.99  # Courant stability factor (S <= 1 for 1D)
dt = Courant * dx / c0  # Time step (s)
Nt = 350        # Total time steps

# Field Initialization
Ey = np.zeros(Nx)
Hz = np.zeros(Nx)

# Pre-computed coefficients
c_E = dt / (eps0 * dx)
c_H = dt / (mu0 * dx)

# Pulse source parameters
t0 = 40
sigma = 10

# Main FDTD Leapfrog Loop
for n in range(Nt):
    # 1. Update H field at (n + 1/2) using E field at n
    Hz[:-1] -= c_H * (Ey[1:] - Ey[:-1])
    
    # Inject Gaussian source into E field
    pulse = np.exp(-0.5 * ((n - t0) / sigma) ** 2)
    Ey[Nx // 2] += pulse
    
    # 2. Update E field at (n + 1) using H field at (n + 1/2)
    Ey[1:] -= c_E * (Hz[1:] - Hz[:-1])

print(f"Simulation completed successfully over {Nt} steps.")

Summary

• The Problem: Maxwell’s curl equations are tightly coupled. Direct spatial/temporal discretization at identical points leads to an infinite recursive loop ($E^{n+1}$ depends on $H^{n+1}$, which depends on $E^{n+1}$).
• The Solution: Kane Yee (1966) staggered $\mathbf{E}$ and $\mathbf{H}$ fields by half a spatial step ($\Delta x / 2$) and half a temporal step ($\Delta t / 2$).
• The Result: An explicit leapfrog algorithm where $H^{n+1/2}$ is computed solely from previous $E^n$ values, and $E^{n+1}$ is computed solely from newly updated $H^{n+1/2}$ values—enabling fast, stable, and memory-efficient computational electrodynamics.

This guide explains the process from Phase 1 (environment setup) to final deployment (push to GitHub), including pitfalls you may face on Arch Linux.

Phase 1 — Setting up the Ruby Environment

Jekyll is written in Ruby, so we need a working Ruby environment first.

Step 1 — Add Ruby to PATH (Arch installs Ruby locally, not globally)

Arch Linux does not place Ruby gems in a global directory by default. Instead, gems are installed under your user directory, so you must configure a dynamic path.

Run the following commands:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. Append a header comment to the bash profile
echo '# Ruby Gems Configuration' >> ~/.bashrc

# 2. Set GEM_HOME dynamically using Ruby
echo 'export GEM_HOME=$(ruby -e "puts Gem.user_dir")' >> ~/.bashrc

# 3. Add gem binaries to PATH
echo 'export PATH="$PATH:$GEM_HOME/bin"' >> ~/.bashrc

# 4. Reload the updated profile in current shell session
source ~/.bashrc

# 5. Verify where gems will now be installed
gem env | grep -E "GEM_HOME|USER INSTALLATION"

Explanation of each line

1. echo '# Ruby Gems Configuration' >> ~/.bashrc Adds a comment to the file for readability. It has no effect on execution but helps you remember why this block exists.

2. export GEM_HOME=$(ruby -e "puts Gem.user_dir")

   • ruby -e runs Ruby code directly in the terminal.
   • Gem.user_dir prints a user-safe directory path where gems should live.
   • $() captures that output and assigns it to GEM_HOME.
   • This makes the path dynamic — it works even if Ruby version changes.

3. export PATH="$PATH:$GEM_HOME/bin" Tells your shell to also check the gem binary folder when you run commands like jekyll or bundle.

4. source ~/.bashrc Loads the updated file without restarting your terminal.

5. gem env | grep -E "GEM_HOME|USER INSTALLATION" Confirms the gem home path and ensures the configuration worked.

Phase 2 — Installing Jekyll and Bundler

1
gem install jekyll bundler

What is Bundler and why is it needed?

Bundler is a dependency manager for Ruby. Jekyll themes and plugins rely on many gems. Instead of installing them manually, Bundler:

• Reads the Gemfile in your project
• Installs the correct gem versions
• Prevents version conflicts
• Makes deployment reproducible on any machine

Without Bundler, your site may run locally but fail to build during deployment.

Phase 3 — Creating the Jekyll Blog

Inside your project folder (you created one named MyBlog), run:

1
jekyll new .

This generates the full blog structure including:

1
2
3
4
5
_config.yml      → Main configuration file
_posts/          → Blog posts live here
Gemfile          → Lists dependencies (themes, plugins, etc.)
index.md         → Homepage
about.md         → About page (you later deleted this file)

Phase 4 — Understanding the Generated Gemfile

Your error earlier was:

1
2
Could not find gem 'minima (~> 2.5)' in locally installed gems.
Run `bundle install` to install missing gems.

This happened because:

• minima is the default Jekyll theme
• It was listed in your Gemfile
• But not installed yet

Fix it by running:

1
bundle install

Pitfall: If Bundler opens an editor like vi during merge, and you don’t have it installed or configured, you may see:

1
2
error: cannot run vi: No such file or directory
error: unable to start editor 'vi'

Solution: Set Git to avoid opening editors during pull:

1
git config pull.rebase false

This forces Git to use merge instead of rebase, and stops editor prompts.

Phase 5 — Writing Your First Blog Post

Create a file under _posts/ like:

1
2025-12-27-github-pages-jekyll.md

Jekyll requires posts to follow this naming format:

1
YEAR-MONTH-DAY-title.md

Phase 6 — Initializing Git for Deployment

Inside your blog folder, run:

1
2
3
git init
git add .
git commit -m "Initial blog draft using Jekyll on Arch Linux"

Phase 7 — Linking to GitHub Repository

You already created a GitHub Pages repo named:

1
ahmad-sakib.github.io

Now link it:

1
git remote add origin https://github.com/ahmad-sakib/ahmad-sakib.github.io.git

Phase 8 — Syncing Local and Remote Repo

If GitHub already contains commits you don’t have locally, pull them first:

1
git pull --no-rebase origin main

Common pitfall message you faced:

1
2
rejected main -> main (fetch first)
Updates were rejected because the remote contains work you do not have locally

This means your local and remote histories diverged. Pulling fixes it.

After pulling, complete the merge if needed:

1
git commit

Phase 9 — Pushing to GitHub

1
git push origin main

This publishes:

• Your blog source code
• Your commits (including file deletions like about.md)
• Triggers GitHub Pages deployment automatically

Phase 10 — Key Pitfalls & How to Avoid Them

You are correct — the webrick requirement should be explicitly documented, especially for Ruby 3.x environments on Arch Linux.

Add the following section in your blog under the Ruby setup or dependency phase:

Phase X — Installing Webrick (Required for Local Jekyll Server on Ruby 3.x)

When you run a Jekyll site locally using:

1
bundle exec jekyll serve

You may encounter an error similar to:

1
cannot load such file -- webrick (LoadError)

Why this happens

• In Ruby 3.0+, the webrick HTTP server library is no longer bundled by default.
• Jekyll still depends on webrick to run its local development server (jekyll serve).
• On systems like Arch Linux, where Ruby is lean and user-scoped, this dependency must be installed manually.

Fix

1
bundle add webrick

or if you prefer installing directly via gem:

1
gem install webrick

After installation, verify it exists in your bundle:

1
bundle install

Now restart your Jekyll server:

1
bundle exec jekyll serve

Your local preview should run without issues.

Recommendation

Even if your site builds on GitHub Pages without a local server, installing webrick is important for:

• Testing posts before publishing
• Debugging theme/layout issues locally
• Ensuring jekyll serve works in your venv-like gem environment

Summary

1. Configure Ruby environment dynamically
2. Install Jekyll + Bundler
3. Generate blog using jekyll new .
4. Install theme dependencies via bundle install
5. Commit changes locally
6. Pull remote changes if needed
7. Push to GitHub to deploy

Jekyll GitHub Pages Blog Project Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
MyBlog/
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.html
├── about.md
├── _layouts/
│   └── default.html
├── _posts/
│   └── 2025-12-27-example.md
├── assets/
│   ├── css/style.scss
│   └── images/
└── _site/ (DO NOT EDIT)

File & Folder Purpose

Important Notes

• The _site/ folder is automatically generated when you run jekyll build or jekyll serve.
  Never edit files inside it, because your changes will be erased on the next build.

• Blog posts must follow the naming format:

  1
  YYYY-MM-DD-title.md
  

  Example:

  1
  2025-12-27-my-first-post.md
  

• Markdown posts can contain YAML front matter at the top, like:

  1
  2
  3
  4
  5
  ---
  layout: default
  title: "Exploring Wave Interactions"
  description: "A physics-based blog post exploring wave superposition and interference."
  ---
  

Typical Workflow (for documentation)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Install Jekyll + Bundler
gem install jekyll bundler

# Create new site
jekyll new MyBlog
cd MyBlog

# Install missing dependency for Ruby 3+
bundle add webrick

# Serve locally
bundle exec jekyll serve

# GitHub workflow
git init
git add .
git commit -m "Initial Jekyll blog setup"
git branch -M main
git remote add origin <your-repo-url>
git pull origin main --rebase  # If remote is ahead
git push -u origin main