¶Ata's PHP-Based Static Site Generator for GitHub Pages

This post is about Ata's SSG at https://github.com/atas/ssg

In my quest to find the perfect static site generator, I encountered numerous remarkable ones packed with features. Some were straightforward, while others were more complex.

However, none truly resonated with my needs:

• Simple HTML, CSS: Easily modify the HTML layout as simple header and footer, CSS and JavaScript files.
• Local Run: No build process. Changes should reflect instantly upon refresh, without restarting or executing commands.
• GitHub Pages: Use GitHub Pages to host the output of the site, after a build process easily.
• Format Support: Adept at handling both markdown, plain HTML and PHP.

I've evaluated notable SSGs like Jekyll, Hugo, Hyde, Astro, Gatsby, and Next.js. Jekyll came close in terms of simplicity. Yet, it lacked real-time local updates, demanded plugins for rudimentary tasks achievable with server-side languages easily, and provided limited theme support on GitHub Pages. Customizing even the most modern theme, Minima, felt like delving deep into Jekyll’s core.

I've always gravitated towards simplicity: plain HTML, CSS, and JS files. With templating languages, I found myself battling recurring syntax lapses. On the contrary, C-syntax, the foundation for PHP, enjoys widespread adoption which is great as a templating language as well, as PHP is.

Initially, I settled for a rudimentary PHP site with Markdown support. Hosting it on a shared server seemed apt. I even created a deployment pipeline triggering upon repository changes. However, the need for caching markdown files quickly became evident as processing files every time for every http request was not super fast. Moreover, ensuring swift PHP responses on shared servers—particularly during peak US hours—proved challenging without resorting to pricier options or maintaining own PHP-Nginx/Apache server on top of servers that already needs to be maintained.

The elegance and simplicity of GitHub Pages always appealed to me. No maintenance woes. No downtime concerns. If only I could harness this with PHP...

That's when the idea struck! Why not use GitHub Actions to process PHP and markdown outputs, convert them to .html, and then deploy on GitHub Pages? This project embodies that vision, spinning up a PHP server within a GitHub Actions container to execute this task. This benefits the local development environment as running the site as a PHP project without a build process.

To streamline the process, specific codes and build procedures have been organized under a system directory. This ensures users only engage with a handful of files to get their site operational on GitHub Pages.

Offered as free and open-source, I hope this tool empowers others to effortlessly deploy their personalized static sites on GitHub Pages. Feel free to send PRs and issues at https://github.com/atas/ssg.