Publishing docs — all chapters
What GitHub Pages is for
GitHub Pages serves a website from a GitHub repository, free, on a github.io address or your own domain. Selfish commits your built site into a repository and Pages serves it. Each publish is one commit, so you get the whole history of your site, and you can always go back.
No git is needed on your device. Selfish makes the commit through GitHub’s API.
In Site Settings → Publishing, set Publish Using to GitHub Pages. There are two ways to give Selfish access: sign in, or paste a token.
Sign in with GitHub
This is the short way. There is no token to copy.
- Make a repository for your site at github.com/new, or decide which existing one to use. Create a Repository in Selfish opens that page. Selfish can’t create a repository for you.
- Choose Sign In with GitHub. Selfish shows a short code.
- Choose Copy Code and Open GitHub. Paste the code on GitHub’s page and approve Selfish. Then come back. The app carries on by itself.
- Choose Choose Repositories on GitHub and give Selfish the repository for your site. Selfish can reach only the repositories you choose there, and nothing else in your account.
- Back in Selfish, pick the repository from the list. If it is the only one, it is chosen for you.
Then publish. Selfish commits the site, and turns GitHub Pages on for you if it is off, serving the branch it published to.
What signing in allows is narrow. Selfish may read and write the contents of the repositories you chose, and switch Pages on for them. It can’t see your other repositories or create new ones. The sign-in is kept in the Keychain like every other secret, it renews itself as you publish, and Sign Out ends it.
With an access token
If you would rather not sign in, choose Use an Access Token Instead.
- Fill in Owner and Repository.
- Choose Create Token on GitHub. It opens GitHub’s form for a fine-grained token with the right permission already selected.
- On GitHub, choose Only select repositories, pick this repository, generate the token, and paste it into Access Token.
- Publish once. Then turn Pages on in the repository’s Settings → Pages, choosing the branch, and the folder, you published to.
The token needs one permission: Contents, read and write, on this repository. If you give it an expiry date, it stops working on that date, and you paste in a new one. A token with only that permission can’t read the repository’s Pages settings, so the checks described under Test Connection below work when you are signed in.
The fields
| Field | What to enter |
|---|---|
| Owner | The user or organisation that owns the repository, for example octocat. Chosen for you when you pick from the list. |
| Repository | The repository’s name, for example my-site. |
| Branch | Optional. Leave it empty for gh-pages. Selfish creates the branch on the first publish if it doesn’t exist. |
| Subdirectory | Optional. A folder to publish into, such as docs. Empty means the top of the branch. This choice changes how publishing behaves, as below. |
A brand-new, empty repository is fine. Selfish starts it with a short README so there is something to build on.
Two ways to lay it out
With no subdirectory, the branch becomes exactly your site. Each publish replaces what was there, so anything you removed since last time disappears on its own. Use a branch kept for the purpose, which is what the default gh-pages is.
With a subdirectory, Selfish publishes into that folder and leaves everything else in the branch untouched. That is the setup for serving Pages from /docs on your main branch, beside other files.
GitHub Pages can serve a branch from its top or from a folder called docs, and nothing else, so a subdirectory with any other name is one Pages won’t serve.
Either way:
- Files that haven’t changed aren’t uploaded again.
- Your custom domain is kept. GitHub stores it in a file called
CNAMEon the branch, and Selfish carries that file over on every publish. - A
.nojekyllfile tells GitHub to serve your files as they are, which makes deploys finish sooner.
Test Connection
Test Connection proves the access and the repository in one go. When you are signed in, so that Selfish may read the repository’s Pages settings, it also notices when everything connects but the site still wouldn’t show, and says what to change:
- GitHub Pages is switched off for the repository.
- Pages is set to build with GitHub Actions rather than serve a branch.
- Pages is serving a different branch or folder from the one you publish to.
- Pages is off and you have chosen a subdirectory it couldn’t serve.
Things to know
- A private repository’s site is still public. And GitHub Pages from a private repository needs a paid GitHub plan.
- A shared draft is a file in your repository. If you share a draft and the repository is public, anyone browsing it can find the draft. Selfish says so when you turn sharing on.
- Photo-heavy sites make large repositories. GitHub asks that a Pages site stay under 1 GB.
- A site with a very large repository can’t use a subdirectory, because GitHub won’t list all its files in one answer. Publish to a branch of its own instead.
Your own domain
With your own domain as the site’s address, Selfish’s Publishing screen shows the DNS records GitHub needs and checks them from your device. See Custom domains.
Problems? See Troubleshooting.