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.

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. 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 Link GitHub.
2. Enter your GitHub username.
3. pageo reads pageo.json from your latest commit on main. Your page content is replaced with the file's content.

After you link, the editor shows your page as synced from GitHub, and GitHub Settings in the sidebar holds the webhook setup.

Update on every push

1. Open github.com/yourname/pageo/settings/hooks and choose Add webhook.
2. Payload URL: https://www.pageo.me/api/github/webhook
3. Content type: application/json
4. Events: Just the push event.
5. In pageo, open GitHub Settings, generate a secret, and paste the same secret in GitHub's Secret field.
6. Choose Add webhook.

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

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 in the Link GitHub dialog. 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.