GitHub Pages
Toucan-based websites can be hosted for free using GitHub Pages. Follow these steps to set up your site.
Creating a repository for your site
You can either create a repository or choose an existing repository for your site.
If you want to create a GitHub Pages site for a repository where not all of the files in the repository are related to the site, you will be able to configure a publishing source for your site. For example, you can have a dedicated branch and folder to hold your site source files, or you can use a custom GitHub Actions workflow to build and deploy your site source files.
If the account that owns the repository uses GitHub Free or GitHub Free for organizations, the repository must be public.
If you want to create a site in an existing repository, skip to the Creating your site section.
- In the upper-right corner of any page, select
+
, then click New repository. - Use the Owner dropdown menu to select the account you want to own the repository.
.github.io or .github.io - Type a name for your repository and an optional description. If you’re creating a user or organization site, your repository must be named
user.github.io
ororganization.github.io
. If your user or organization name contains uppercase letters, you must lowercase the letters. For more information, see About GitHub Pages. - For the repository visibility, choose public. For more information, see About repositories.
- Select Initialize this repository with a README.
- Click Create repository.
Add content to the repository
- Clone the Repository locally to your computer, if not already done:
git clone https://github.com/your-username/your-repository.git
- Navigate to the local repository folder and copy the
src
folder with all the content.
Use the generator’s serve command:
After succesfull generation all the data is generated inside thetoucan generate
docs
folder by Toucan. - Push all the content to GitHub, add and commit files:
git add . git commit -m "Add generated site content" git push origin main
Creating your site
Before you can create your site, you must have a repository for your site on GitHub. If you’re not creating your site in an existing repository, see Creating a repository for your site.
- On GitHub, navigate to your site’s repository.
- Under your repository name, click
Settings
. If you cannot see theSettings
tab, select the...
dropdown menu, then clickSettings
. - In the
Code and automation
section of the sidebar, clickPages
. - Under Source, leave the option
Deploy from a branch
. - Under Branch:
- Select the branch where you committed your files (e.g., main).
- Choose the /docs folder as the source.
- Click Save.
- Check the published site, GitHub will provide a public URL for your site, such as:
https://your-username.github.io/my-github-page/
Managing a custom domain
You can set up or update certain DNS records and your repository settings to point the default domain for your GitHub Pages site to a custom domain.
- On GitHub, navigate to your site’s repository.
- Under your repository name, click
Settings
. If you cannot see theSettings
tab, select the...
dropdown menu, then clickSettings
. - In the
Code and automation
section of the sidebar, clickPages
. - Under
Custom domain
, type your custom domain, then click Save. If you are publishing your site from a branch, this will create a commit that adds aCNAME
file directly to the root of your source branch. If you are publishing your site with a custom GitHub Actions workflow, noCNAME
file is created, so you need to create one manually (containing only a line of text with your custom domain). - Navigate to your DNS provider (e.g., Namecheap, GoDaddy, Cloudflare) and update the DNS records.For Apex Domains (e.g., example.com), set up an
A
record pointing to GitHub’s IP addresses:
For Subdomains (e.g., www.example.com), set up a185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153
CNAME
record pointing to:
(Replace “username” with your GitHub username)username.github.io
- Enforce HTTPS (Optional but Recommended)
- After DNS propagation (may take a few minutes to 24 hours), go back to GitHub Pages settings.
- Ensure
Enforce HTTPS
is enabled