GitHub sync and pageo.json

With GitHub sync, your page lives in a pageo.json file in a GitHub repository. Each push to the main branch updates your page. GitHub sync is free.

GitHub sync is not the GitHub contributions section. That section shows your contribution chart on your page, and you add it from the editor. GitHub sync replaces your page's content with a file from your repository.

Set up the repository

1. On GitHub, create a public repository named pageo under your own account, for example github.com/yourname/pageo.
2. Add a pageo.json file at the root of the main branch. To keep your current page, copy the file that the GitHub sync page shows under Start from your current page. Or start from the example below.
3. Set email in the file to the email address of your pageo account. pageo checks it, so only you can link the repository.

Link it to pageo

1. In your pageo admin sidebar, under Account, choose GitHub sync.
2. Enter your GitHub username and choose Check repository.
3. Choose Link repository, then confirm. pageo reads pageo.json from your latest commit on main, and your page content is replaced with the file's content.

After you link, the GitHub sync page shows the repository, when it last synced, and the commit it synced from. Sync now reads the file again.

Update on every push

On the GitHub sync page, follow Update on every push:

1. Copy the payload URL: https://www.pageo.me/api/github/webhook
2. Choose Generate and copy, then Save secret.
3. Open github.com/yourname/pageo/settings/hooks and choose Add webhook. Paste the payload URL and the secret, set the content type to application/json, and choose Just the push event.

Pushes to other branches are ignored. The secret is optional, but without it pageo cannot confirm that a push came from GitHub.

Edits in the editor

Changes you save in the editor stay in pageo and do not reach GitHub. The next sync replaces them. To keep the two the same, copy the file under pageo.json on the GitHub sync page into your repository and commit it.

Unlink

Unlink GitHub at the bottom of the GitHub sync page stops syncing and resets your page to a clean default. The repository on GitHub is not changed.

Example pageo.json

{
  "email": "you@example.com",
  "profile": {
    "name": "Maya Chen",
    "role": "Product designer",
    "bio": "I design calm software for small teams. **Booking for spring.**"
  },
  "socialLinks": [
    { "type": "github", "href": "https://github.com/mayachen" },
    { "type": "x", "href": "https://x.com/mayachen" },
    { "type": "linkedin", "href": "https://linkedin.com/in/mayachen" }
  ],
  "gridLinks": [
    {
      "title": "Icon set",
      "description": "120 calm interface icons",
      "image": "https://example.com/icons.png",
      "url": "https://mayachen.design/icons",
      "layout": "grid",
      "isPrimary": true
    }
  ],
  "settings": {
    "layout": "grid",
    "showContactForm": false
  }
}

Field reference

Top level

profile

socialLinks[]

The order in the file is the order on your page.

gridLinks[]

pageo numbers the links from their order in the file, so you never set id or order yourself.

settings

When a sync fails

pageo keeps your current page. When you link, the reason shows under the username on the GitHub sync page. For a push, open the webhook on GitHub and check Recent Deliveries:

• Repo or pageo.json not found: check the repository name (pageo), the branch (main), and that the file sits at the root.
• Not valid JSON: run the file through a JSON validator. A trailing comma is the usual cause.
• Does not match the required schema: compare the file with the reference above. Every required field must be present.
• Email does not match: set email to your pageo account email.