Creating a GitHub Pages site

Publii includes support for Github Pages, which provide a space for you to build a website that you can use for highlighting your Github projects, or just yourself! Unfortunately, there's little functionality for actually building a website unless you have some know-how and are willing to learn difficult-to-setup tools such as Jekyll, but thanks to Publii you'll be able to create a full-featured, stunning website in just a few minutes that's super-easy to update and maintain.

Creating a Github Page doesn't take long, but there's a few steps we'll need to cover, starting with:

Generating an access token

Before we can start creating a Github Page, we need to generate an access token; this will allow Publii to gain access and make changes to your Github Page so that it can create and edit your website whenever you click the Sync button in the Publii app; think of it as creating a password that Publii can use to get into the Github club!

The steps below use a personal access token (classic). The screenshots show an earlier GitHub interface, so some labels and menu positions may differ:

1. Start by heading over to the Github frontpage and sign-in to your account; if you don't have an account already just click the Sign up link and complete the registration process.

   

2. After logging-in, open your Github profile settings.

   

3. In the left-sidebar of your profile screen, click on the Developer settings.

   

4. On the GitHub Apps page, in the left-sidebar, click on the Personal access tokens option and select the Tokens (classic) option.

   

5. Now we're on the Personal access tokens page; we need to make a new one for our site, so click on the Generate new token button near the top of the screen and select Generate new token (classic) option.

   

6. On the next screen, fill out a name in the Note section e.g. "Publii GitHub Page". Now in the Select scopes section, add a checkmark to the main Repo option, which will give the token access to all aspects of managing your repository. You can also set an Expiration date for your token e.g. "90 days" to help keep your information secure. Finally, click the green Generate token button at the bottom of the screen.

   

7. You'll now be taken back to the Personal access tokens page, but now your new token will be visible at the top of the list. Whatever you do, don't close or refresh this page; the token will only be visible immediately after generation. Click on the Copy icon next to your token (see the image below), and copy it somewhere safe as we'll need it when setting up Publii to work with our Github Page.

   

   Remember: you won't be able to see the token again so make sure it's saved somewhere.

We now have a token generated, so we can create our website in Publii and give it access to our Github page.

Creating our static website on Github Pages

We already have our access token, so this will allow Publii to access our Github Page to upload the website files, but now we have to actually create the area on Github where our site will go. Let's go back to Github and get started:

1. Log-in to Github as normal, then click the plus icon in the topbar to open a submenu; now click on the New repository option to be taken to the Create a new repository screen.

   

2. On this screen, fill out a Repository name, and leave the repository as Public for this guide. GitHub Pages requires a public repository on GitHub Free; supported paid plans can also publish from private repositories. Next, click the green Create repository button at the bottom of the screen.

   

3. Now we're on the Quick setup screen; this might seem a little confusing, but we only need to do one simple thing here. Click on the README link as shown in the pic below; this will take us to a screen for creating a readme file.

   

4. On the edit screen for the readme, commit the new file. This creates the initial commit and the default branch, usually main, which Publii needs before it can upload your website. If you publish to the repository root, Publii will remove this README file during the first sync. If you publish to a subfolder, the README outside that folder is not part of the sync.

   

5. After committing the file we're taken back to the file listing; click on the Settings tab near the top of the screen.

   

6. On the settings screen, click Pages in the left sidebar. Under Build and deployment, set Source to Deploy from a branch. Select main (or the branch you created) and /(root), then click Save. If you want to publish from a subfolder, use /docs after Publii has uploaded that folder, as explained below.

   

7. After saving, your GitHub pages will be ready to be used as a static website host; to view your website you'll need to go to the URL provided in the message box. Sometimes you may need to refresh the page you are currently viewing to see the URL box. Of course, your site doesn't have any files yet, but we're going to change that.

   

And that's it for the Github side of things; now we can jump over to Publii for the final step.

Syncing your Publii static site with Github

With everything prepared on Github, we can update the connection settings in Publii to sync with the Github Page repository that we just created. First, open up Publii; if you haven't already created your website, create one, select a theme and add the content you want to publish.

Now click on the Server option in the left-sidebar to open the Server Settings screen, and select GitHub Pages as the deployment method. Fill out the fields with the following information. The screenshot above predates the Folder field added in Publii 0.48.2:

• Website URL - Enter the published website address shown in your repository's Settings > Pages, usually YOUR_USERNAME.github.io/YOUR_REPOSITORY_NAME for a project site. Select HTTPS separately and leave the https:// prefix out of the text field. If you publish from /docs, do not add /docs to the website address.
• API Server - By default, this field is already completed with the standard API server. However, if you are running your own instance of GitHub, you can change the API server by entering it here.
• Username / Organisation - Enter the GitHub username or organisation that owns the repository.
• Repository - Enter the name of your Github repository here (we set this in step 2 of the Github Page section above).
• Branch - Enter main if you followed this guide, or the name of another existing branch. It must match the branch selected in GitHub's Pages settings. The token owner must have permission to push to that branch.
• Folder - Available from Publii 0.48.2. Leave this field empty to upload to the root of the selected branch, or enter a subfolder such as docs. Publii manages the website files within the selected folder. This is a repository path, not part of the website URL.
• Token - Remember the access token we saved in the first part of this guide? Enter that here so that Publii can access the repository.
• Parallel Uploads - Defaults to '1'. Sets the number of upload streams that Publii can use when uploading your site content to GitHub Pages. Higher numbers allows for faster uploads, but can cause errors on slow connections, or an error 403 due to API upload rate limits.
• API rate limiting - Disable this option only if you are using Github Enterprise with disabled API rate limiting. Otherwise disabling this option can cause deployment errors.

When GitHub Pages publishes from a branch, its source folder must be either /(root) or /docs. To use /docs, enter docs in Publii's Folder field. After the first sync creates the folder, select /docs under Settings > Pages on GitHub and save the change. Other upload folders, such as public, can be used with external hosting services or a custom GitHub Actions workflow.

Important: With Folder left empty, Publii manages the entire selected branch and removes files that are not part of the generated website. Use a dedicated branch or a subfolder if the repository contains other files you want to keep.

If you change an existing Folder setting, Publii displays a warning when you save:

• From the root to a subfolder: the old website files remain in the root. Remove them manually if they are no longer needed.
• From one subfolder to another: the old folder remains. Remove it manually if it is no longer needed.
• From a subfolder to the root: the next sync manages the entire selected branch and removes files and folders that are not part of the generated website, including the old upload folder.

Once all the options are set, click Save settings, then Test connection to check access to the repository and branch. If the test fails, check the account, repository, branch and token settings.

Everything is now ready, so we can click the Sync your website button in the Publii sidebar to start deployment.

IMPORTANT! A completed sync means that your files have reached GitHub. GitHub Pages may take a few minutes to publish them. Check the Pages workflow in your repository's Actions tab for deployment progress or errors. You can also open the Commits list and inspect the status beside the latest commit:

An orange status dot indicates pending checks. Open the status details to see whether the Pages deployment is still running or needs attention.

Limitations

Keep the following limits in mind when using Publii's GitHub Pages deployment method:

• Website size: Publii 0.48.2 stops synchronization if the generated website directory contains more than 4,000 files and directories in total. Subdirectories count towards this limit.
• Individual files: Publii 0.48.2 checks new and changed files before uploading. If any exceed 30 MB, synchronization stops and Publii lists the affected files. Reduce their size or remove them from the website before trying again. This is the limit enforced by Publii's GitHub upload method.
• API requests: GitHub normally allows 5,000 authenticated REST API requests per hour for a personal access token. This allowance is shared with other API activity for the same account. With API rate limiting enabled, Publii checks whether enough requests remain for the upload. GitHub also applies secondary limits, so large or highly parallel uploads can still be throttled. If you reach a limit, wait before trying again; 5,000 requests does not mean 5,000 website files.

Some Useful Tips and Tricks

Looking to get a bit more control over your site? Here's some useful tricks that will help your site get exactly how you want it:

Simplify your website URL to yourusername.github.io

By default your Github page URL will be username.github.io/repository-name, but we can simplify this by creating a repository for our website called yourusername.github.io e.g. if my username is TestName, I would create a repository called TestName.github.io.

Then, instead of duplicating the URL as TestName.github.io/TestName, Github will simplify the URL to TestName.github.io only.

Use a custom domain

If you'd prefer to use your own domain name rather than the default github.io subdomain, add it under Settings > Pages > Custom domain on GitHub, then configure its DNS records. Enter the same domain in Publii's Website URL field and sync again. Publii includes a CNAME file with the custom domain in the uploaded website files.

Follow the custom domain tutorial from GitHub. For a domain without a subdomain, such as example.com, use the instructions for configuring an apex domain.

To keep the repository private and serve the site through Cloudflare, see Configure Cloudflare Pages with Publii.

Is SSL available for your custom domain?

All github.io subdomains have SSL enabled by default, also the HTTPS is supported for Github Pages that have custom domains.

Use different branches in your repo

In our tutorial we specifically use the main branch of our repo, but you are free to use other branches; you could create a documentation website for your existing repository by using a docs branch, for example. Create the branch first, select it as your GitHub Pages source and enter the same name in Publii's Branch field. A branch named docs is separate from the /docs folder: the Branch and Folder settings control different parts of the upload destination.

IMPORTANT! Before syncing, check both Branch and Folder in Publii. If Folder is empty, Publii removes files outside the generated website from whichever branch is selected, even if you intended to publish to another branch.

Download Publii