README.md

Superface Documentation

This repository contains the documentation website code and Markdown source files for https://superface.ai/docs.

Contribute to docs

1. Run the docs locally

• Clone the repo, then yarn install and yarn start

2. Update the content

• Make your desired changes to the documents inside /docs directory
  It uses a standard Markdown syntax, but can be extended with custom React components via MDX.

  ^{Help for Markdown features ➚}

• Put your static content (e.g. images) to /static directory
  When linking to it from the docs, just drop /static from path, e.g. rendering /img/diagram.png will render an image saved at /static/img/diagram.png.

  ^{Help for static assets ➚}

• Reference other docs via Markdown file path
  Linking to another document is preferably done via specifying the relative path to that document (./next-step.md). Exceptions are pages placed in src/pages/ directory that need to be linked using their respective routes.

  ^{Help for referencing docs ➚}

3. Update the content structure (optional)

• Page rename, new page, category; or change of structure
  If you added a whole new category, page or simply want to change the table of contents, you'll need to update sidebars.js. It uses document IDs that are simply a path to the file minus the extension (unless explicitly defined inside the document).

  ^{Help for Sidebar ➚}

• Changing links in header navigation
  Navigation links are defined in docusaurus.config.js in themeConfig.navbar.items object.

  ^{Help for config ➚}

4. Get the changes reviewed

• When you're happy with your changes, open a PR and get it reviewed by someone.
  Opening a PR will automatically deploy an online preview of your docs. It also verifies the build doesn't contain any broken links.

5. Deploy to production

• Once your changes are verified and reviewed by another pair of eyes, it is ready to be merged to main.
  Merging will automatically deploy main branch to production.

Tech Stack

These docs are built using Docusaurus 3.

Details

The site is deployed on Vercel.

All deployments are automated via GitHub Actions and you can keep track of them in the repository's environments.

• Preview: gets deployed for each PR
• Production: gets deployed continuously from main branch

Each deploy first verifies the validity of the build.

If you'd like to build locally:

yarn build

License

The Superface documentation is licensed under a Creative Commons Attribution 4.0 International license.