Plinto: a CMS that lives inside the site
You know how every aspiring teenage developer built their own CMS back in the day? I’m now long past being a teenager, but I couldn’t help myself. I built a CMS!
We wanted to rebuild our company website and the obvious choice was a static-site generator. We wanted to let our frontend developer build a site using React components, but it was also important that editing and translation were easy for non-technical people.
For that I built Plinto. It is an admin UI for Astro sites that stores content in MDX pages in Git, and it is bundled into the deployed site itself.
The admin has no server
One thing really annoyed me. If the site is statically hosted and doesn’t need more than simple GitHub Pages hosting, where should the admin live? I don’t want to run a server just to host the admin. Then I discovered isomorphic-git.
Other CMSes like Decap and Sveltia work with content in git, but use each hosting provider’s API. I chose to use isomorphic-git instead, so we clone the entire repo to a filesystem (lightning-fs) running in IndexedDB in the browser.
This means the admin is a part of the static site. When you go to /plinto/admin on the deployed site, the repository is cloned into your browser. Saving a page makes a local commit, and publishing pushes the commits. You can use GitHub Pages or similar to deploy your site on push.
You still need one thing that’s outside your browser, though. GitHub doesn’t accept cross-origin requests, so you need a small CORS proxy for that. I’ve made a small template for a Cloudflare Worker that is included in the repository.
For authentication, each editor needs a GitHub token and a Claude API key. That’s the login. There’s a system for combining a username, GitHub token and Claude API key into a single base64 token that an admin sends to a new editor. The admin makes a separate GitHub token for each editor, one that can only write to the site’s repository. The base64 token is not encrypted, so treat it like a password. For security reasons, Plinto does not store the token. You need to log in on each page reload in the admin. With a password manager it’s bearable.
The GitHub token and the Claude API key are still in the page while you edit. The admin also runs your site’s code, because it renders your components. This means a malicious npm dependency in your site could read them.
Media files should be set up to be stored in Git LFS, so that the clone stays small. Plinto implements LFS support which isomorphic-git lacks. The clone is not shallow at the moment, so a repository with a long history takes longer to clone.
When you run astro dev on your own computer, the same admin reads and writes the files in your actual working directory on your dev computer, so hot reloading still works. Pushing from Plinto is disabled in dev mode.
Editing with your own React components
Plinto uses Puck, a visual block editor where the blocks are your own React components. Using a small adapter, Plinto opens an MDX page in Puck and writes it back as MDX. The file has frontmatter, import statements and component tags. So the storage format is one real MDX file per page. This way, Astro can read and render the content without Plinto being involved.
Since the admin is bundled into your site, the editor renders your actual components.
Puck is a block-level editor, and a website author can only change the props of a component, which the frontend developer has chosen to make editable. That is intentional. It keeps editors from breaking the layout or making a page ugly.
There is also a media picker. When you “upload” an image, it is downscaled and written to the filesystem in your browser. It is uploaded to LFS when you publish.
Plinto also has collections, for things like your staff or your news items. A collection entry is an MDX file like a page, but it has no URL of its own. Plinto gives your components a hook to read a collection, and the admin can edit the entries. They are translated the same way as pages.
Note: The editor can’t handle top-level prose. It only opens pages that are made entirely of components. If a page has Markdown text outside a component, the editor refuses to open it, so that it doesn’t rewrite the page.
Translation
Plinto is built for multi-lingual content. The admin shows which language versions of a page are out of date, and it can translate the changes into the other languages using the Claude API.
To translate, it gives an LLM the changes and lets it edit the existing translation, so the corrections you made in the translation are kept. I wrote about that idea in Three-way translation merge: keeping translated pages in sync with an LLM. The bookkeeping is done by a separate library, Obelum.
The LLM is Claude, and it runs in the browser with each editor’s own Anthropic API key. Editing, saving and publishing work without a key.
Claude also helps with git conflicts. If someone else published while you were editing, git merges in the browser. The files git can’t merge go to Claude, which tries to resolve conflicts, but asks you questions when it can’t decide.
What Plinto doesn’t do
Plinto only does the admin. It adds its admin routes to the Astro site but does not involve itself with the build process. Everything else, like routing and i18n, is done by Astro as usual. If you remove Plinto, the site still builds.
Status
Plinto is early. I use it for our company website, cupmanager.net.
It needs Astro 6 or 7 and React 19.
To try it, clone the repository and run the example site:
git clone https://github.com/maxmart/plinto
cd plinto
npm install
cd examples/playground
npm run dev
The example site is at /en/ and the admin is at /plinto/admin. Setup for your own site is in the package README.
If you try it and something breaks, please open an issue.