tinalabs / tinacms-doc-toolkit Goto Github PK

View Code? Open in Web Editor NEW

0.0 4.0 0.0 14.76 MB

A toolkit for creating isolated documentation sites for Tina plugins, utilities, and packages.

Home Page: https://tinalabs.github.io/tinacms-doc-toolkit/

JavaScript 7.00% TypeScript 90.61% CSS 2.39%

tinacms-doc-toolkit's Introduction

Welcome to the react tinacms documentation toolkit

Getting started

Create a new docs site: npx create-next-app --example https://github.com/tinalabs/tinacms-doc-toolkit/tree/master/packages/example-site-next docs
Then navigate to the docs site: cd docs
And start the dev server and follow the on-screen instructions: npm run dev

You can see further instructions for getting started and using the toolkit in the documentation.

Note

This toolkit comes pre-configured to deploy to Github pages, with a Github actions workflow stored in the .github folder.

If you create a new Github repository with this site, it will automatically deploy to Github pages.

Setting up from scratch

Please see SETUP.md for instructions on how to get up a nextjs site from scratch using the plugin

tinacms-doc-toolkit's People

Contributors

Watchers

tinacms-doc-toolkit's Issues

Update to look like TinaCMS docs

Make it look like the TinaCMS docs, minus:

The docs sidebar
The docs footer

The table of contents should reflect:

The pages in the tina-demo.config.js
The h2s in the MDX doc you're currently viewing

Add a CRA example

Same as Next example -- ideally they would share MDX files somehow. A script to copy them at build time?

add floating action button to toggle tinacms

add new fonts to heading and body

Refactor to a catch-all route file for index and slug routes in next demo

[[...slug].tsx

export default ExampleComponent() {
  // logic
}

export const getStaticPaths: GetStaticPaths = () => {
  return {
    params: {
      slug: "/"
    },
    fallback: false
  }
}

export const getStaticProps: GetStaticProps = (context) => {
  // do your thing
}

Wrap up MDX logic in react router for CRA

This can be exported as a DemoRouter from tinacms-demo-toolkit

Update README.md of the Next starter

Explain what it's for
Explain how to use it (link to GitHub Pages docs site)

Document deploying CRA/Next.js to Vercel

Or generate a deploy button for the user in the README.md

Pull config into a tina-demo.js config file in root of example sites

Build and test all pull requests

add new page and prev page button from tinacms doc pages

add heading styles from tinacms doc pages

Update next starter README.md

Explain what it's for
Explain how to use it (link to GitHub Pages docs site)

Deploy demo of toolkit to GitHub Pages on changes to main

Update README.md to send people to hosted docs

# tinacms-demo-toolkit

Some kind of description. [Learn more](https://tinalabs.github.io/tinacms-demo-toolkit)

Add toc styles from tinacms docs

Include Github Actions deployment to GitHub Pages in starters

MDX logic

Overview

Documenting a third-party plugin should be easy, fun, and interactive for the end-user.

Tina plugins are hard to reason about in text-based documentation, much easier to reason about visually.

Scope

A JSON config specifies which MDX files are part of the demo. This is used by helpers for CRA and Next.js to generate routes for every specified MDX file on-the-fly.

As each route is rendered, the MDX will be processed with remark and mdx to become the body of the page.

Value

MDX will allow users to import the pieces of their plugin code in markdown documentation, making integration documentation painless and easy.

Appetite

1 person, 2 days.

Make it easy to configure Tina from MDX

Bake in loadComponent

Right now we're only supporting Next.js and CRA, so we know a web pack loading strategy will work.

I also don't think we should scope it to mdx files.

If we include it in the tinacms-demo-toolkit package, and make the loadComponent prop of Layout optional, defaulting to the baked in logic if its undefined, that would be better.

This works 100% for MDX, TSX, TS, JS, and JSX:

export const loadComponent = async (fileName: string) => {
  try {
    const component = await import(`../docs/${fileName}`);
    return component;
  } catch (e) {
    console.error(`${fileName} was not found`);
    console.error(e);
    throw e;
  }
};

E.g, doing:

|- docs/
|--- page/
|---- content.mdx
|---- code.tsx
|---- index.ts

index.ts

import Content from "./content.mdx";

export default Content;

It works just fine.

Wrap up mdx logic for next.js

Lets put the next.config.js logic inside an imported method:

export function configureNext(config: any) {
  config.pageExtensions: pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'];

  return withMDX(config);
}

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
})

next.config.js

import { configureNext } from "tinacms-demo-toolkit";

module.exports = (phase, { defaultConfig }) => {
  const config = defaultConfig;

  return configureNext(config);
}