Using TinaCMS with Docusaurus

Docusaurus is a powerful React-based SSG for creating beautiful documentation websites with ease. Given it's designed primarily for docs maintainers, the user experience is built around working with the filesystem and editing files directly. It's a very flexible system that leverages multiple filetypes, meta file configuration, javascript files with hard-coded content, and auto-generation. With TinaCMS you can leverage the powerful features of Docusaurus from a simple but flexible editing UI.

This guide is based on adapting the Docusaurus Classic Example to work with TinaCMS's basic editing. You can find the completed TinaCMS + Docusaurus starter here.

Setup

To start, we have to shape the data to be more consistent so it will align with the schema we're going to write. The docs and blog content is a mixture of .md and .mdx files alongside some .json meta files used to describe how the folders get displayed in the "docs" sidebar. We'll remove the meta files given we're going to write a schema for the sidebar to be manually controlled by the editor, and we'll migrate all the .md files to .mdx. For the blog, we'll extract the filename embedded dates to the MDX frontmatter, and we'll inline authors given TinaCMS's reference system is based on individual file references and not a single data file like authors.yml.

For managing images with TinaCMS you'll want a central folder for all your images, which can contain subfolders for docs or blog specific images as needed. Move all the collocated images to the static folder and update them in the .mdx files as needed.

Docusaurus supports globally registered .mdx components so you don't have to import them locally. We'll register all the components we'd like to set up for editing with TinaCMS so they can be added from the rich text editor.

Next, we'll have to modify sidebar.js, docusaurus.config.js and pages/index.js to pull data from .json files so the content can be edited in TinaCMS. By default Docusaurus's sidebar is autogenerated, so this also means replicating the existing sidebar data and setting the sidebar to manually generate from our data. Docusaurus is flexible but still requires data to take a certain shape, so you'll need to write a parsing function to shape it as needed.

Now that our data is ready it's time to write a TinaCMS schema. This is where you have the power to create exactly the editing experience that you want. In TinaCMS content is contained in collections, here's an example of the schema for the docs collection:

You can see you have control over what the data looks like, what fields are required, what UI is used, where the content is located, what format it's in, and more. Given your schema is JavaScript you can render anything you want, including a custom warning component:

Editing

Once we've written our schema and everything's wired up, we'll be able to edit from TinaCMS's UI.

Editing the blocks-based homepage with TinaCMS:

Figure: Editing the Docusaurus example homepage in TinaCMS

Editing an MDX page with TinaCMS:

Figure: Editing MDX Docusaurus Page in TinaCMS

Notes

This only scratches the surface of what you can do with both Docusaurus and TinaCMS; to learn more about Docusaurus, check out their docs.