GitHub Pages Setup, Initial Attempts and Challenges

Initial Setup with GitHub Pages

Our initial approach to deploying PresidentPedro.com involved utilizing GitHub Pages. We aimed to leverage its simplicity for hosting static websites. However, we soon encountered several challenges that required us to rethink our strategy.

Single Development Branch

We began with a single development branch in our Git repository. This branch contained all our project files, including 11ty source files and the generated _site folder. We quickly realized that this structure would present some issues.

Successful Custom Domain Configuration

On the positive side, we successfully configured our custom domain (presidentpedro.com) to work with GitHub Pages. This involved:

• Adding A records in our Squarespace DNS settings (where our domain is managed).
• Creating a CNAME file in the root of our repository with our custom domain.

This confirmed that we could point our domain to GitHub Pages, which was a crucial first step.

The `index.html` Requirement

We observed that GitHub Pages had specific expectations regarding the index.html file. When we placed a simple index.html file in the root of our repository, it was correctly served at presidentpedro.com. However, this revealed a key limitation: GitHub Pages expects to find a static `index.html` file in the root of the repository.

The `index.njk` Challenge

When we attempted to use our 11ty template file (index.njk) as our index page (replacing the static `index.html`), we encountered a 404 error. This highlighted the fact that GitHub Pages doesn't directly process Nunjucks templates. It serves static files, and our 11ty build process generates these static files.

Local Development Setup Success

In parallel with our GitHub Pages attempts, we successfully set up our local development environment. We encountered no significant issues with Node.js or npm installation. This was a positive step, as it allowed us to work more efficiently locally.

GitHub Pages Limitations and File Structure Issues

The primary challenges we faced were related to GitHub Pages' limitations and our initial repository file structure:

• GitHub Pages' requirement for a static index.html file in the root.
• Our single-branch structure, which mixed source files and generated output.
• The inability of GitHub Pages to directly process 11ty templates.

A New Approach: Best Practices and Shareability

After several attempts to find a workaround that would satisfy GitHub Pages' requirements, we decided to take a different approach. We wanted to establish a project structure that:

• Adhered to best practices.
• Would work beyond the limitations of GitHub Pages.
• Would be easy for other beginners to understand and follow.

We realized that relying on workarounds to accommodate GitHub Pages would ultimately lead to a more complex and less maintainable project. We wanted to create a project that we could confidently share with others, without overwhelming them with immediate, GitHub Pages-specific solutions.

The Decision to Restructure

This realization led us to the decision to restructure our repository and implement a proper build and deployment process. This involved adopting a multi-branch strategy and leveraging GitHub Actions to automate the build and deployment, which we will cover in the next document.