Quick start

This page goes from a fresh clone to editing a Hugo site, first locally and then through GitHub. If you only want to try Emet out, the local part is enough and takes about two minutes.

Editing a local site#

Clone and install:

git clone https://github.com/dmyates/emetcms.git
cd emetcms
npm install

Then start the dev server with HUGO_ROOT pointing at your Hugo site:

HUGO_ROOT=/path/to/your/hugo/site npm run dev

Open http://localhost:5173. There’s no login in this mode. The sidebar lists your content sections, and clicking an entry opens it with its frontmatter as a form above the body. Edit something and press Save; the file on disk changes and nothing else happens. If you have hugo server running in another terminal, the preview pane can show you the real rendered page.

The first time you do this, Emet writes admin/site.yaml and admin/cms.yaml into your Hugo site. Those files are the configuration for everything you’ll see in the editor. The generated version is a reasonable guess from your existing content, but it is a guess, so have a look at Configuration before you commit them.

Deploying it#

To let other people edit a site that lives on GitHub, you need a deployed copy of Emet and a GitHub App for sign-in.

1. Create a GitHub App and note its client ID.

2. Build with the client ID:

   VITE_GITHUB_CLIENT_ID=Iv23.your_client_id npm run build

3. Deploy to Cloudflare Pages. The functions/ directory contains the OAuth token exchange, and Pages picks it up automatically.

Note that this is not a “deploy dist/ anywhere” situation. Signing in needs the /api/github/token endpoint, which only exists on Cloudflare Pages unless you run your own proxy and point VITE_API_BASE_URL at it. Deployment covers both cases.

One deployment serves any number of sites: the repository you edit is chosen after sign-in, not at build time.

Signing in and editing#

1. Open your deployed CMS and click Sign in with GitHub.
2. Pick a repository and a branch. If your Hugo site lives in a subdirectory of the repository, Emet detects that, or you can type the path.
3. If the repository has no admin/site.yaml, the setup wizard runs, scans the site and commits a config for you.
4. Edit as before. This time, each save is a commit to the branch you picked.

If you configured a production_branch, your saves land on the working branch and the Sync with Production button in the header opens a pull request to production, which you can review and merge from inside Emet. See Publication.

Where next?#

• Entries for how editing, saving and drafts work.
• Visual mode and Markdown mode for the editor itself.
• Desktop app if you’d rather edit a local folder in a proper window than in a browser tab.