Skip to content

GitHub Pages App

About

GitHub pages compatible repos can be published using this app.

Publishing pages

Pages can be published by pushing the GitHub pages repo via SSH or HTTP.

SSH

To publish your page via SSH:

  1. You must save your SSH public key to /app/data/ssh/authorized_keys using the File manager.

  2. Add SSH remote and push

    git remote add page ssh://git@<app.example.com>:<sshport>/app/data/repo.git
    git push page master

The SSH Port can be configured in the Location section of the app.

HTTP

Use SSH key instead

This method is not recommended since it involves storing your credentials in plain text. We recommand using SSH keys instead.

To publish your page via HTTP:

    git remote add page https://<app.example.com>/_git/page
    git push page master

When pushing, git will prompt for Cloudron username and credentials. Any Cloudron user with access to the app can push.

It can be convenient to store the HTTP username and password in the ~/.netrc file:

    machine app.example.com login fred password bluebonnet

Adjust app.example.com, fred and bluebonnet above to your setup.

Build Branch

By default, the app renders the master branch. To change this, edit /app/data/env.sh using the File manager:

export BUILD_BRANCH=main

Be sure to restart the app, after making any changes.

Jekyll

The app uses the pages gem to statically build the website.

Limitations:

  • Only Jekyll 3 is supported. For Jekyll 4, you must build the site manually.
  • Only the plugins listed in the pages plugins page are supported.

Using mkdocs

mkdocs has a command called gh-deploy that can automatically build docs and publish the site to a specific remote and branch.

To force skip of Jekyll build, create a file name .nojekyll at the root of the repo.

    git remote add page https://site.cloudron.xyz/_git/page # add the github-pages app remote
    mkdocs gh-deploy --remote-name page --remote-branch master --force

Jekyll 4

This app only supports automatic build of Jekyll 3 websites. To publish a website with Jekyll 4:

  • Install Jekyll locally with sudo gem install jekyll.
  • Build the site locally on your laptop with jekyll build.
  • Add the _site to your git repo.
  • Add a .nojekyll at the root of the repo.
  • Push to the pages app.