Skip to content

How to turn your GitHub Readme into a static website

Posted by author in the category "tutorials"
Example of a static website created from a GitHub Readme

Creating a HydePHP site on GitHub Pages based on your Readme

Welcome to the HydePHP blog! Today, we're going to show you how to create a simple static site from your GitHub project's file using HydePHP and deploy it using GitHub Pages.

In case you're not already familiar, HydePHP is a static site generator that combines the power of Laravel with the simplicity of Markdown. With just a few steps, your next website is minutes away from becoming a reality.

Getting Started


  • A GitHub repository with a file.
  • GitHub Actions enabled for your repository.
  • GitHub Pages enabled for your repository.

Step-by-Step Guide

1. Create the Workflow File

First, we need to set up a GitHub Actions workflow file. Create a new file named .github/workflows/build.yml in your repository. This workflow will handle the process of converting your into a static site and deploying it to GitHub Pages.

Here is the example workflow:

1name: Build Documentation from Readme
4 push:
5 branches: [ "main" ] # Make sure this matches your default branch
8 build:
9 runs-on: ubuntu-latest
11 permissions:
12 contents: read
13 pages: write
14 id-token: write
16 steps:
17 - uses: actions/checkout@v3
19 - name: Create site from Readme
20 run: |
21 # Here we set up the HydePHP source files to use the as the index page
22 mkdir _pages
23 mv _pages/
24 rm -rf !'_pages'
26 - name: Create Hyde config
27 run: |
28 # Configure the site name
29 echo 'name: My Site Name' >> hyde.yml
30 # Optionally, load styles from the CDN
31 echo 'load_app_styles_from_cdn: true' >> hyde.yml
32 # Optionally, use Highlight.js for syntax highlighting
33 echo "scripts: '<link rel=\"stylesheet\" href=\"[email protected]/build/styles/atom-one-dark.min.css\"> <script src=\"[email protected]/build/highlight.min.js\"></script> <script>hljs.highlightAll();</script> <style>.prose :where(pre) { background-color: #282c34; } </style> <style>pre code.hljs { padding: 0; }</style>'" >> hyde.yml
35 - uses: hydephp/action@master
36 with:
37 deploy-to: "pages"

This workflow performs the following steps:

  1. Checks out the repository.
  2. Moves the file to the _pages directory and renames it to
  3. Creates a basic HydePHP configuration file (hyde.yml) with the site name and optional style settings.
  4. Uses the HydePHP GitHub Action to build the site and deploy it to GitHub Pages.

2. Enable GitHub Pages

To deploy your static site, you need to enable GitHub Pages in your repository settings. Follow these steps:

  1. Go to the Settings tab of your repository.
  2. Click on the Pages tab in the sidebar.
  3. Under Build and deployment, select GitHub Actions from the Source dropdown.

GitHub Pages Settings

This step allows the HydePHP GitHub Action to deploy your site directly to GitHub Pages.

Why HydePHP?

HydePHP offers a fast and convenient way to create and deploy static sites. Here are some key benefits:

  • Ease of Use: HydePHP is incredibly easy to set up and use, making it perfect for quick project landing pages or documentation sites, with plenty of room to grow, thanks to its Laravel foundation.
  • Bundled Frontend: You don't need to design any HTML or write any JavaScript or CSS. HydePHP comes with a beautiful, responsive Tailwind frontend out of the box.
  • Powerful Features: While simple to start, HydePHP can scale to support more advanced features as your project grows. And of course, every single part of HydePHP is customizable to your liking.


In just a few steps, you've learned how to create a static site from your file using HydePHP and deploy it with GitHub Actions. This method is perfect for getting a landing page up and running quickly for your open-source projects. HydePHP is here to make web development fun and smooth again!

We hope this tutorial helps you get started with HydePHP. Happy building!

Additional Resources

For more information, visit the HydePHP GitHub Action documentation.

If you have any questions or run into issues, feel free to reach out to the HydePHP community for support at any of the following channels: GitHub | Discord | Twitter

Please note that HydePHP is not affiliated with GitHub or GitHub Pages. GitHub terms and fees may apply. At the time of writing, GitHub Actions and GitHub Pages offer free tiers for public repositories.

Syntax highlighting by

End of article