Embeddable Handbook

This is the repo for Embeddable's Docs.

It uses the Nextra site generation framework (Documentation).

It is currently deployed and managed on Vercel.

Any changes pushed to the main branch are automatically deployed to https://docs.embeddable.com.

Documentation Guidelines

Writing

• Please follow our style guide

Structure

• Keep nesting no more than two levels deep (e.g. Connect your data > Integrations > Cube Cloud).
• Avoid using dropdowns as pages. They can be tricky to navigate, especially on mobile.

Clone repo

Use git clone [email protected]:embeddable-hq/handbook.git

Troubleshooting:

• You may need to generate an SSH key and add the SSH key to your github account.

Local Development

Install pnpm, e.g: npm install -g pnpm

Run pnpm i to install the dependencies.

Then, run pnpm dev to start the development server and visit https://localhost:3000.

Remove Cookie banner

The cookie banner will constantly appear.

Hack to fix this:

• in _document.tsx update line 16 to be: })(window,document,'script','dataLayer','DO-NOT-COMMIT');

Git UI

These are popular git UI tools:

• Github Desktop
• Sourcetree

Testing final app

Run pnpm build to build the app

Run pnpm run start to preview the built app

Deploying

Sometimes, the left sidebar is cached, causing strange behaviour when deploying.

When deploying:

• Go to Vercel.
• You'll see your branch.
• Click three dots.
• Select latest deployment.
• In the top right, click the three dots.
• Click Redeploy.
• Make sure 'use existing build cache' is unticked.

Prepping media

• Resize to max 1250px width for videos and images.

To resize videos:

1. Convert file to .mp4: https://www.freefileconvert.com/
2. Resize it: https://ezgif.com/resize-video/ezgif-6-478b77626d11.mp4

To resize images

1. https://www.iloveimg.com/resize-image
2. https://compresspng.com/

To avoid caching issues in Vercel

We have set this environment variable in the Vercel platform:

VERCEL_FORCE_NO_BUILD_CACHE to true

To test for broken links

Use a tool like https://www.deadlinkchecker.com/

License

This project is licensed under the MIT License.