2024 Update: We now have a custom GitHub Action that makes it even easier to build and deploy HydePHP sites. Check out the HydePHP GitHub Action for more information.
Introduction
HydePHP is a framework for building static websites. While the most common way to interact with HydePHP is through the command line, you can actually manage an entire site using GitHub.
In this tutorial, we will do the following, right in our browser!
- Create a new Hyde project.
- Setup a CI/CD pipeline to automatically compile the site.
- Deploy the site to GitHub Pages.
TL;DR
Impatient? Here is a link to the workflow we'll be creating: https://github.com/hyde-staging/ci-demo/blob/master/.github/workflows/main.yml, and here is a live preview: https://hyde-staging.github.io/ci-demo/
Prerequisites
This guide assumes you are moderately familiar with GitHub and Actions and will not go into detail on the basics. There are links to the GitHub documentation at the end of the article in case you get stuck.
Step 1: Create a new Hyde project
While the traditional way to create a new Hyde project is using composer in the command line, here we'll take advantage of the fact that the Hyde repository acts as a complete template.
To create our project, navigate tohttps://github.com/hydephp/hyde. On this page, you will see a big green button that says "Use this template".
Let's click it! Tip: You can also use this direct link https://github.com/hydephp/hyde/generate
Next, fill in the repository details, then press the "Create repository from template" button. This will then create a brand new repository with everything we need to set up our Hyde site!
Having issues? Check out the GitHub documentation for this subject.
Step 2: Setting up the GitHub Actions workflow
There are many ways and methods to use GitHub Actions, I personally like decoupling jobs. So for our workflow, we will use two jobs, one to build the site, and one to deploy it.
We will use workflow artifacts to pass the built data between the jobs. Don't take this as gospel though, you can use any method you like.
From your GitHub repository page, head on over to the Actions tab, and hit the "New workflow" button. On this page, you want to select the "set up a workflow yourself" button. This will create a new workflow file in your repository. Here we'll add the first job, to build the site.
1# This is a basic workflow to help you get started with using HydePHP with GitHub Actions 2 3name: Build & Deploy 4 5# Controls when the workflow will run 6on: 7 # We only want to run this workflow when changes are pushed to the master/main branch 8 push: 9 branches: [ "master" ]10 11 # Allows you to run this workflow manually from the Actions tab12 workflow_dispatch:13 14# A workflow run is made up of one or more jobs that can run sequentially or in parallel15jobs:16 # First we need to build the site17 build:18 # The type of runner that the job will run on19 runs-on: ubuntu-latest20 21 # Steps represent a sequence of tasks that will be executed as part of the job22 steps:23 # Checks-out your repository under $GITHUB_WORKSPACE, so the job can access it24 - uses: actions/checkout@v425 26 # (optional) Validate the Composer files to catch any errors early on27 - name: Validate composer.json and composer.lock28 run: composer validate --strict29 30 # (optional) Cache the Composer packages to speed up future builds31 - name: Cache Composer packages32 id: composer-cache33 uses: actions/cache@v434 with:35 path: vendor36 key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}37 restore-keys: |38 ${{ runner.os }}-php-39 40 # Install the Composer packages41 - name: Install dependencies42 run: composer install --prefer-dist --no-progress43 44 # Now we can build the site! We do this using the HydeCLI45 - name: Build the site46 run: php hyde build --no-interaction47 48 # Our site is now compiled into the _site directory, so we'll upload it to an artifact to use in the next job49 - name: Upload site artifact50 uses: actions/upload-artifact@v451 with:52 name: site53 path: _sitePaste the code above into the web editor and commit the changes.
Head on over to the Actions tab, here you'll see a new workflow called "Build & Deploy" which should already be running, otherwise it will start shortly. When it's finished, which for me took just half a minute, click on the run link. This will take you to a page where you will see that an artifact called "site" has been created.
If you want, you can click on the artifact to download the zip file to your computer. Open it up, and you'll see that your site is now built and ready to be deployed!
Step 3: Deploying the site to GitHub Pages
We're almost there! Now we need to deploy the site to GitHub Pages. There are two routes we can go here, we could just upload the compiled site into the docs/ directory, however, I prefer to have it on a dedicated branch, so that's what we will do here, but you can use any method you like.
Preparing the repository
Stuck? See https://docs.github.com/en/pages/quickstart for help.
First, you need to enable the Pages feature on your repository. This is done by going to the repository settings page, and clicking on the "Pages" tab, and selecting the gh-pages branch as your site source.
Don't have a gh-pages branch? I created mine in the web interface by selecting a Jekyll theme on the pages settings tab and then removing the two generated files. This quickly left me with an empty gh-pages branch. If you know a better way to do this using the web editor, please let me know!
Updating the workflow
Now that our repository is ready, we need to update our workflow to upload the site to the new GitHub Pages branch.
Add the following code after the build job in the workflow we made before:
1# Now we can deploy the site to GitHub Pages! 2deploy: 3 runs-on: ubuntu-latest 4 needs: build # Run the build job first, otherwise we won't have anything to deploy 5 6 steps: 7 - uses: actions/checkout@v4 8 with: 9 ref: 'gh-pages' # Checkout the gh-pages branch10 11 # (optional) Remove any old files from the gh-pages branch12 - name: Empty site directory13 run: rm -rf *14 15 # Download the compiled site into the current directory16 - name: Download site artifact17 uses: actions/download-artifact@v418 with:19 name: site20 path: '.'21 22 # Create a .nojekyll file to prevent GitHub from attempting to compile a Jekyll site23 - name: Create .nojekyll file24 run: touch .nojekyll25 26 # Commit the changes to the gh-pages branch27 - name: Commit changes28 uses: EndBug/add-and-commit@v929 with:30 add: '.'31 message: 'Upload compiled site ${{ github.sha }}'Now when you commit the changes, the site will be built and uploaded to GitHub Pages.
Congratulations! You've now set up a new site with HydePHP and GitHub Actions. From here on, the opportunities are limitless. Why not try out creating a few new pages? You can also customize your site in the config files.
You can keep managing your site in the cloud using GitHub, or you can clone the repository to take advantage of the powerful realtime compiling and content scaffolding offered by the HydeCLI.
Next steps
If you want to take your CI further, here are some ideas that the HydePHP.com DocsCI uses:
-
Hyde already comes with compiled Tailwind CSS for all the built-in templates, however, if you add your own classes, you can always use the pre-installed Laravel Mix feature to compile the assets in the CI build process.
-
Want to enable code syntax highlighting? Hyde has first-party support for Torchlight.dev, an API service for amazing syntax highlighting. Note that Torchlight requires a (free) API token. You should never store credentials in your GitHub repository. Instead, store the API key in your GitHub Action Secrets and add it to your .env file during the CI build process.
Syntax highlighting by Torchlight.dev