tinacms / tinacms

A fully open-source headless CMS that supports Markdown and Visual Editing

Tina is a headless content management system with support for Markdown, MDX, JSON, Yaml, and more.

It comes with a GraphQL API:

• Query your Markdown content like this 👉 post.author.firstName
• Supports statically generated and server side rendered pages
• Supports references between documents

Tina offers a live preview (optional and opt-in) that makes editing Markdown files very intuitive for less-technical people.

Getting Started

Test a TinaCMS starter site locally

npx create-tina-app@latest

Or try a demo site on Tina Cloud.

Documentation

Visit Tina's documentation to learn more.

Questions?

Visit the GitHub Discussions or our Community Discord to ask questions, or look us up on on Twitter at @tinacms.

Contributing

Please see our ./CONTRIBUTING.md

Maintainers

• Jeff See (@jeffsee55)
• James O'Halloran (@jamespohalloran)
• Logan Anderson (@logan_anders0n)
• Kelly Davis (@kldavis)

All Contributors ✨

Thanks goes to these wonderful people (emoji key):

Forestry.io 💵	NCPhillips 📆 💻 📝 🐛 📖 🤔 🚇 🚧 👀 ⚠️	DJ 📆 💻 📝 🐛 📖 🤔 🚧 👀 ⚠️	Scott Byrne 🎨 💻 👀 🚧 📖 📝	James O'Halloran 📆 🐛 🤔 🚧 👀 ⚠️ 💻 📝	Kendall Strautman 🎨 📆 🐛 🤔 🚧 📢 👀 💻 📝	Nichlas Wærnes Andersen 💻 🎨 🤔
Jordan 📆 📢 🤔 🐛 🚇 📖 💻	Frank Taillandier 👀 📖 📆 📓 🐛 💻	Scott Gallant 📖 📢 🔍 📝	Mitch MacKenzie 📓 📝	zacchg 📓	Lyle Underwood 🐛 💻	Laura1111999 📖
Thom Krupa 📓	Michael Gauthier 📓 📖	dcgoodwin2112 📖	akshayknz 📖	Adam Silverstein 📖	Brad McGonigle 💻	Jake Coxon 💻
Ladislav Prskavec 💻	Bolarinwa Balogun 🚇	Mason Medeiros 📓	ironsean 📓 📖 💻	kyp 🐛	Vladislav Shkodin 🐛	maciek_grzybek 🤔 💻 🚇
weibenfalk 📹 📝 💻	David Bergeron 🐛	Kellan Martin 💻	Jon Miller 🤔	Paul 🐛	Chris Flannery 💻 📖	Jefferson Bledsoe ⚠️ 📖
Kenia 💻	Andrew James 💻	Zach B 📢	Jyoti Puri 💻 👀 ⚠️ 🚧 🐛	nibtime 💻 🐛	Johan Soulet 💻 🐛	Cleiton Pereira 🐛 🤔
chrisdmacrae 🚇 💬 🤔	jhuggett 💻	Nicolas Cisco 💻 ⚠️	Hungry Bear Studio 💻	Alex Barbato 💻	Dani Tulp 💻 🤔 📖	PaulBunker 💻
JavaScript Joe 💻	Madelyn Eriksen 📝	Marc Mintel 🚇 💻 🐛	Jeff See 🚇 💻 🚧 ⚠️ 👀	Brandon Landfried 🐛	Chad Johnson 🐛	David Arnold 🤔
Gavin McFarland 🐛	blandfried 🐛 💻	Mark Lawlor 🤔	Ben Scott 👀	Brent Mitton 💻 📖	Colin McGraw 📖	Brandon Shackelford 💻 🐛
Amy Kapernick 🐛	Sam Ullman 🐛	Andreas Adam 🤔 📖 💻	Stephen Sugden 📖	Logan Anderson 💻	Isabella Brookes 💻	Lukas Strassel 💻 📖
Lauren Clark 📖	Ar Nazeh 📖	David Royer 📖	Tulsi Prasad 📖	Jan Vlnas 📖	Omar Costa Hamido 📖 🐛	Kelsey Edelstein 📖
CodeItQuick 🐛	Justin Menga 💻	Luke Digby 📖	Erwann Mest 📖	Frank Noirot 📖	Matthias 📖	crouton 🐛
Alexandre Boucher 💻	Can Rozanes 💻 🤔	Yann Vanhalewyn 🐛	Artem Artemyev 🐛 💻	Lachlan McKay 💻 🐛	Matthew Francis Brunetti 💻 🐛	Joe Innes 📖 💻
Austin Condiff 💻 🤔	pristas-peter 🐛 💻	Dan Beaven 💻	Hirvin Faria 📖	Travis Miller 💻	Chris Davis 💻 🚧 ⚠️ 👀	SaintMalik 📖
Jeremy Epstein 📖 💻 🔌	Eddie Arpin 💻 🐛	ryuurock 💻	Xavier Mirabelli-Montan 💻 🐛 🤔	Phoenix-Alpha 💻 🐛 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

tinacms's Issues

Sidebar advance pane (via hamburger)

`cms`: separate field plugin management from form management

Problem

FormManager currently has two responsibilities:

1. track the forms in the CMS
2. track the field plugins in the CMS

Possible Solution

Extract a FieldsManager that tracks the field plugins

querying formatted dates does not re-format on save

Querying for a date field and passing in the formatString function will change the date format on the frontend, and this is not converted back to the appropriate format on save. This will cause subsequent builds to fail.

Proposed solution:

1. add a date field type
2. determine if the front matter field is a date and automatically apply the date field type with reasonable defaults

xserver: pass child plugin config to extendXserver callback

Add a Menu to the markdown Wysiwyg

Field - Flashy field (for demo)

Ideas:

• Tweet field
• Image field with unsplash.com images
• Icon picker field

`yarn build` fails on files and demo projects

Problem

Running yarn build fails.

Cause

It assumes that everything in packages is (1) a directory and (2) contain Typescript projects meant to be built with rollup.

Both of these assumptions are wrong.

1. There is a .keep file in `packages.
2. The cra-demo and gatsby-demo packages have their own build scripts.

Options

1. Fix the build script so it doesn't fail on those cases.
2. Move the build script into it's own package

• Have cms and other ts packages import the build package
• Build all packages with lerna run build

I think I like option 2 more

Field - image

gatstby-plugin-tinacms: TypeError post is null

Sometimes, while editing a document, the post becomes null and the website breaks.

Make float or fixed

Suggestion to make this configurable:

   resolve: "gatsby-plugin-tinacms",
   options: {
      dock: {
        style: "floating" | "fixed",
        position: "right" | "left,
      }
   }
}```

Support editing Links in markdown Wysiwyg

Remove @tinacms from non-internal packages before launch

In order to keep these packages private until launch, we have to prefix them with @tinacms. However we do not want this to be the case post-launch. Here's are the packages which must be renamed:

• tinacms
• react-tinacms
• react-tinacms-json
• react-tinacms-remark
• gatsby-plugin-tinacms
• gatsby-tinacms-git
• gatsby-tinacms-gitlab

Add Babel Plugin for better style debugging

Currently debugging style issues is terrible, there's no naming or context when you're looking at the devtools. For example, if you're trying to debug styles, the outputted classnames are basically gibberish. This plugin would help with that by appending the actual component name to the class name, as far as I understand.

Example from their docs: In your page source you'll see: <button class="Button-asdf123 asdf123" /> instead of just <button class="asdf123" />.

Seems like we would need to add babel to rollup and then also use this preset to make it work with typescript.

Tina periodically blows up while editing markdown content

After a blow-up, refreshing the page brings things back to normal.

See screenshot:

←→1 of 2 errors on the page
TypeError: Cannot read property 'frontmatter' of null
PageTemplate
src/templates/page.js:1
> 1 | import React from 'react';
  2 | import { graphql } from 'gatsby';
  3 | import { Helmet } from 'react-helmet';
  4 | import { remarkForm} from '@tinacms/react-tinacms-remark';
View compiled
▶ 17 stack frames were collapsed.
JSONStore._this.handleMittEvent
/Users/scott/Documents/projects/forestry-local/tina/tinacms-site/.cache/json-store.js:1
> 1 | import React from "react"
  2 | 
  3 | import PageRenderer from "./page-renderer"
  4 | import normalizePagePath from "./normalize-page-path"
View compiled
▶ 2 stack frames were collapsed.
r.<anonymous>
/Users/scott/Documents/projects/forestry-local/tina/tinacms-site/.cache/socketIo.js:20
  17 | // Try to initialize web socket if we didn't do it already
  18 | try {
  19 |   // eslint-disable-next-line no-undef
> 20 |   socket = io()
  21 | 
  22 |   const didDataChange = (msg, queryData) => {
  23 |     const id =
View compiled
▼ 18 stack frames were expanded.
r.emit
http://localhost:8000/socket.io/socket.io.js:6:13528
r.onevent
http://localhost:8000/socket.io/socket.io.js:8:10717
r.onpacket
http://localhost:8000/socket.io/socket.io.js:8:10339
r.<anonymous>
http://localhost:8000/socket.io/socket.io.js:8:12513
r.emit
http://localhost:8000/socket.io/socket.io.js:6:13528
r.ondecoded
http://localhost:8000/socket.io/socket.io.js:6:19521
a.<anonymous>
http://localhost:8000/socket.io/socket.io.js:8:12513
a.r.emit
http://localhost:8000/socket.io/socket.io.js:6:13528
a.add
http://localhost:8000/socket.io/socket.io.js:6:11867
r.ondata
http://localhost:8000/socket.io/socket.io.js:6:19474
r.<anonymous>
http://localhost:8000/socket.io/socket.io.js:8:12513
r.emit
http://localhost:8000/socket.io/socket.io.js:6:13528
r.onPacket
http://localhost:8000/socket.io/socket.io.js:6:28879
r.<anonymous>
http://localhost:8000/socket.io/socket.io.js:6:26491
r.emit
http://localhost:8000/socket.io/socket.io.js:6:13528
r.onPacket
http://localhost:8000/socket.io/socket.io.js:7:8856
r.onData
http://localhost:8000/socket.io/socket.io.js:7:8805
WebSocket.ws.onmessage
http://localhost:8000/socket.io/socket.io.js:8:6527
▲ 18 stack frames were expanded.
This screen is visible only in development. It will not appear if the app crashes in production.
Open your browser’s developer console to further inspect this error.```

Blow up when inputting incorrect CSS

While using Tina I added an img tag and some in-line styles. I put in the CSS value, but not the key (instead of style="border: blue" I just did style="blue"), causing my site to blow up upon closing the HTML tag. That page became no-longer accessible so I couldn't fix my issue. I could see editors locking themselves out of pages like this a lot. 🤔

<img src="tinaCMS-demo.gif" style="blue">

Performance problems in Firefox & Safari

Tina is currently unusable in the tinams-site for Firefox and Safari.

Typing at a continuous and moderate pace slows down the UI substantially. I'm not just talking about the time it takes to rebuild the pages, I'm talking about an ever increasing delay in the form's textarea actually visually updating. The data seems fine, all of the keypresses are handled correctly, it just eventually takes many seconds for the UI to catch up. It seems to me that this is an issue with Tina in the browser, and has nothing to do with the server side i.e. file writing or gatsby builds.

I ruled out file-writing because I simplified the @tinacms/api-git endpoint to the bare minimum and it didn't make a difference. Also, if it was a file-writing issue I would expect to see the same issue on the gatsby-starter-blog.

Although I suspect that gatsby build times will be an issue for large sites (e.g. gatsbyjs.org) it does not seem to be this issue. To test this hypothesis, I turned on Autosave afterDelay 100ms in VSCode and began to edit the content. Gatsby had no problem keeping up with the changes being written from VSCode.

Whatever the problem is, it is browser-dependent. I cannot reproduce the issue in Chrome; it only happens in Safari and Firefox. The Firefox profiler shows that typing in the textarea drops the FPS from 60 to 0.23.

I suspect is likely a combination of inefficient React components and CSS rules that computationally difficult.

I will investigate further next week.

react-tinacms-remark: deletes front matter data if it's not been queried for

If a front matter field is not queried for in your template, then it will be removed from the file once the user starts editing that file in the CMS.

failing test: deleteEmpttyHeading should delete an empty heading

This test is currently failing, even though the function works.

Output

* deleteEmptyHeading › should delete an empty heading

    RangeError: Selection passed to setSelection must point at the current document

      19 |         )
      20 |         // Set the seleciton to be at the start of the paragram
    > 21 |         .setSelection(Selection.near(state.doc.resolve($cursor.pos - 1)))
         |          ^
      22 |     )
      23 |   }
      24 |   return true

      at Transaction.setSelection (../../../node_modules/prosemirror-state/src/transaction.js:62:13)
      at deleteEmptyHeading (src/Wysiwyg/commands/heading-commands.ts:21:10)
      at PMTestHarness.apply (src/prosemirror-test-utils/index.ts:68:12)
      at Object.<anonymous> (src/Wysiwyg/commands/heading-commands.test.ts:16:8)

Certain layouts breaking UI

In the layout of the site being edited, I believe in the div#gatsby-focus-wrapper, if something is position: fixed or absolute, said layout doesn't obey the grid being set up by the parent div of the iframe & this content.

Also, if this is happening, you are unable to interact with the ui unless you put a z-index on the iframe. Interestingly in this layout where I see the issue, I haven't set the z-index on anything (iow they're all 0), so if I just put z-index:1 on the iframe, it then becomes usable i.e. clickable & events pass to it etc.

It's an interesting problem... and could be difficult to make this ui foolproof given the myriad layouts / setups out there. Could we test out a modal version of the UI to try and mitigate??

This is the repo I am referencing with the issue - https://github.com/kendallstrautman/starter-blog-gatsby/tree/xeditor - I'd be happy to test it with other layouts & setups as well to flesh out what we need to consider in designing the ui.

Hide Sidebar Toggle in Production

Add "Toggle" field to the xeditor

Some text data represent links to an image.

Here's an example of some data:

draft: true

The field definition might look something like

let fields = [
  { 
    name: "draft", 
    label: "Draft", 
    component: "toggle"
  },
]

CSS in sidebar - can't import css within the sidebar

Css cannot be imported within the sidebar code. I tried adding rollup-plugin-postcss to the build process, but the styles are added in the main document's head (outside of the iframe).

With rollup-plugin-postcss, you can specify extract: false, so maybe the sidebar can include the built css files within the iframe's head?

Added rollup-plugin-postcss here: #94

When creating a new page the file name doesn't get URL-encoded

For my page title I typed Make your site editable with TinaCMS.
The file name became make-your site editable with tinacms.md
and the URL became http://localhost:8000/make-your%20site%20editable%20with%C2%A0tinacms/

We'll want to URL-encode the title somehow

Field - Select

Field - Markdown

Opening a form immedately writes to disk

Steps to Reproduce

• Add a remarkForm to your site
• Browse between pages

You will see it make a write to disk for each file that you visit.

npm or yarn?

lerna is configured to use npm but all the scripts reference yarn

Which should we go with?

Vote
🚀 npm
🎉 yarn

Configure xeditor heading

The user should be able to configure the sidebar:

• Name
• Icon

Field - Date

@tinacms/api-git fails to save because user info is missing

Problem

Hitting the "Save" button on a Remark Form fails.

The following error message shows up in the Gatsby console:

*** Please tell me who you are.

Run

  git config --global user.email "[email protected]"
  git config --global user.name "Your Name"

to set your account's default identity.
Omit --global to set the identity only in this repository.

fatal: unable to auto-detect email address (got 'ncphillips@Nolans-MBP.(none)')

cannot run multiple instances of gatsby-xeditor-git at once

It is possible to run multiple gatsby sites at once locally, it just changes the port.

However, the gatsby-xeditor-git server does not update the port number, so it will break.

Make float and fixed.

Float or fixed mode

   resolve: "gatsby-plugin-tinacms",
   options: {
      dock: {
        style: "floating" | "fixed",
        position: "right" | "left,
      }
   }
}```

xserver: pluggable middlewares

enable plugins to add middlewares to xserver

cms-scripts: add a watch command

#60

Sidebar / "edit mode" UX

I'd like to think about what the UX is going to be for activating and using the sidebar editor. One of the challenges with xeditor is that, by living on the same page as the website, it needs to be accessible without polluting the visuals of the website too much. Think about the kinds of things you'd want to be able to examine on the website as you get real-time feedback while editing.

things to think about:

• options for invoking sidebar / "edit mode"
• Make sidebar resizable
• Possible to open sidebar in new window? (think like chrome devtools)
• making authentication as seamless as possible

Add ESLint to project

Add a very simple ESLint config that works with:

• Prettier
• Typescript
• Javascript
• React

Provide optimized production build

https://overreacted.io/how-does-the-development-mode-work/

wrapFieldsWithMeta should display the description

The wrapFieldWithMeta higher order component should add a description below the label.

If it does this, the user could add a description to the field definition in their forms:

{
  name: "title",
  component: "text", // or "textarea", "toggle", etc.
  label: "Title",
  description: "The title of the page",
}

Which would look something like...

Add "Group" Field

Some data is organized into objects. We want to provide a UI for rendering the data in those objects grouped together.

Here's an example of some data:

title: Hello World
author:
  firstName: Billy
  lastName: Joel

The field definition might look something like

let fields = [
  { name: "title", label: "Author", component: "text" },
  {
    name: "author",
    label: "Author",
    component: "group",
    fields: [
      { name: "firstName", component: "text" },
      { name: "lastName", component: "text" },
    ]
]

xserver plugin: core cms backend

refactor current git backend

the core cms backend writes changes to local filesystem

Close pop out menu with escape key or clicking outside of menu

We should be able to close the little pop-out menu on the bottom (on bottom) with escape key or by clicking out side of the menu.

xserver: pluggable routes

allow plugins to create routes in xserver

we should probably prefix all routes to reduce the chance of name collisions w/ the actual website

would be great if the route prefix is configurable too

Provide Feedback on package sizes in PRs

Problem

NPM package bloat is a real possibility. We don't want packages to get too big, especially from accidentally building with a bunch of dependencies.

Possible Solution

1. Use a tool (e.g. danger) to add a comment to PRs containing a table displaying each package and it's size in kb.

DX: Configuring Remark Forms

Configuring Remark Forms

User Type

• Developer

Devs

• add xeditor to a gastby site
• set the label and descriptions on the form's fields
• add a totally new field to the markdown file

gatsby new my-blog https://github.com/gatsbyjs/gatsby-starter-blog
cd my-blog
// Follow the "Manual Setup" in the docs: https://github.com/forestryio/cms/blob/master/docs/README.md

Our Goals

• identify challenges in switching from implicit to explicit fields
• see if the docs effectively guide the dev
• find out what questions the devs ask next

Field Plugins should be able to define validation functions

FieldPlugins should be able to include a "validate" function.

Reduce friction adding new packages

Problem

Adding new packages is cumbersome and error prone.

Possible Solution

Add a script for creating new packages

> npm run create-package <folder-name>
What should this package be called? (Default: <folder-name) 
What is the first version? (Default: 0.1.0)

xserver plugin: git backend

commit, pull push

use configured ssh creds?

should this be distinct from core cms backend or rolled into it?

Gatsby -- JSON Form only accepts one node

Issue: The JSON form currently assumes that you only pass it one node at a time.

However, if someone has their json modeled as an array of objects, gatsby creates multiple nodes for each object in the array. So we have one json file, but containing multiple nodes (of json objects).

If you map over each node and add an individual form to them, this result in separate individual files to edit for each object. If you only pass the form one node, the other nodes (other json objects with relevant data) will be deleted in the source file.

To replicate

Check out the toc.json data file in the tinacms-site repo. This is an example of the content structure references above.

The query for this json data occurs in layouts/index.ts. You will see that the query says allTocJson , as opposed to just tocJson, which would just return the first node or obj from the data.

The json data (an array of objs) gets passed down to Navigations.tsx where it is mapped over....

<DocumentationNav onClick={() => dispatch({ type: NavigationActionTypes.TOGGLE_DRAWER })}>
          {navigation &&
          navigation.map(({ node }) => {
            return(
            <NavigationMenu key={node.title} menuKey={node.title} node={node} />)
          })}
</DocumentationNav>

If you try to use the useJsonForm hook here, you will get a fields is undefined error.

I made a branch to set up a test case.

Gatsby Plugin: local server for writing changes to markdown files

Problem

When running Gatsby develop, it should be possible to configure the useRemarkForm to write content changes to disks instead of committing to the github API.

This feels more natural and would allow Devs to rapidly edit content and code at the same time.

Possible solution

Use Gatsby-Node to start a Node server that can write markdown changes to disk

Field - Image (Gatsby)