Skip to content

Latest commit

 

History

History
94 lines (69 loc) · 5.9 KB

README.md

File metadata and controls

94 lines (69 loc) · 5.9 KB
Raw

Pages CMS

Pages CMS is an Open Source Content Management System built for static websites (Jekyll, Next.js, VuePress, Hugo, etc).

It allows you to edit your website's content directly on GitHub via a user-friendly interface.

Documentation

For full documentation, go to pagescms.org/docs

How it works

Pages CMS is built as a Vue.js app with a few serverless functions to handle the Github login.

It is intended to be deployed with Cloudflare Pages, using Cloudflare Workers (referred to as functions functions) for the serverless code.

In a nutshell:

  • The serverless functions are just facilitating the OAuth dance (and logout) between the client and GitHub. The GitHub OAuth token is actually stored in the client.
  • Once logged in, the Vue app lets you select the repo (and branch) where your content may be at.
  • You can configure each repo/branch by adding a .pages.yml that describes the content structure and related settings (e.g. media folder).
  • The Vue app acts as a user-friendly interface on top of the GitHub API to manage content related files in your repo. With it you can search and filter collections, create/edit/delete entries, upload media...

Get started

Use online

The easiest way to get started is to use the online version of Pages CMS. You'll be able to log in with your GitHub account and get the latest version of Pages CMS.

This online version is identical to what's in this repo and as mentioned above, nothing is saved in the backend (OAuth tokens are saved on the client side).

But you can also install your own version locally or deploy it (for free) on Cloudflare following the steps below.

Install locally

To get a local version up and running:

  1. Install dependencies: npm install.
  2. Create a GitHub OAuth app: 0n GitHub, go to your Developer Settings and create a New OAuth App (or alternatively create one for one of your organizations). You can use the following settings for your development environment:
    • Application name: Pages CMS (dev)
    • Homepage URL: https://pagescms.org
    • Authorization callback URL: http://localhost:8788/auth/callback
  3. Create a file for environment variables: copy .dev.vars.exmple into .dev.vars and replace GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET with the values you got for your GitHub OAuth app. You shouldn't have to modify BASE_URL.
  4. Run it: npm run dev. This should run the app locally with Wrangler (allowing us to run the serverless functions locally).
  5. Visit localhost:8788.

Deploy on Cloudflare

  1. Prerequisite: you'll need a Cloudflare account (it's free). Once you have one:
  2. Create a Cloudflare Pages app:
    1. From your account dashboard, go to Workers & Pages, then click on Create application and select the Pages tab.
    2. From there you can connect your GitHub account and select the repo you want to deploy (assuming you've forked pages-cms/pages-cms).
    3. Cloudflare will give you a public URL (e.g. https://pages-cms-123.pages.dev).
  3. Create a GitHub OAuth app: same as for local, go to your Developer Settings and create a New OAuth App (or alternatively create one for one of your organizations) with the following settings:
    • Application name: Pages CMS
    • Homepage URL: https://pagescms.org
    • Authorization callback URL: https://pages-cms-123.pages.dev/auth/callback (replace https://pages-cms-123.pages.dev with whatever URL Cloudflare generated for you, or the custom domain you set up)
  4. Add the environment variables to Cloudflare:
    1. Go back to your Cloudflare Pages app, click on the Settings tab and select Environment variables in the sidebar.
    2. Fill in GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET with the values you got from GitHub.
    3. You will also need to set BASE_URL to the URL that was given to you when you create the Cloudflare Pages app (e.g. https://pages-cms-123.pages.dev).
  5. Open the app link (e.g. https://pages-cms-123.pages.dev).

Cloudflare has very generous free tiers and can also host your actual website. It's a great alternative to GitHub Pages, Netlify or Vercel.

License

Everything in this repo is released under the MIT License.

TODO

  • Support for 3rd party file services (AWS S3, Cloudflare R2, etc).
  • Create an embeddable widget or split view with preview.
  • Integrate build status.
  • Display build URL.
  • Allow users to sign up with email.
  • Add proper MDX support in Codemirror.
  • Add saved views (search, sort, order).
  • Add support for groups of collections/files.
  • Add support for other git services (e.g. Gitlab, Bitbucket).
  • Add configuration wizard.
  • Add schema validation for .pages.yml.
  • Add merging/conflict resolution.
  • Add support for partials/weidget in rich-text.
  • Improve handling of network issues (e.g. Github API unreachable).
  • Add checks for extension, size and type in file upload (consider moving to a composable).
  • Add content file validation against schema.
  • Add support for JSON/TOML frontmatter and TOML files.
  • Improve date support (shouldn't require field in schema).
  • Consider a store (Pinia) to save and cache data (config schema, collections, raw URLs...).