Netlify SDK

SDK for developing integrations on Netlify.

Documentation

The documentation lives in https://developers.netlify.app/. If you want to edit the documentation, you can do so here.

Autogenerated SDK API Reference using Typedoc

We autogenerate the SDK API Reference using Typedoc and typedoc-plugin-markdown. The idea behind this is that we can leverage TypeScript to automatically generate the API documentation, and all we need to do is add comments where we deem them necessary.

• The configuration for Typedoc can be found in typedoc.json.
• If you want to see the output that is generated you can run pnpm api-docs.
• If you want to ignore/hide something from the docs. You can use the excludeNotDocumentedKinds configuration in typedoc.json or use @hidden or @ignore.
• Check out the other options in the Typedoc Documentation.

How it automatically adds it to the SDK Docs

This repository has a GitHub Workflow that generates this API reference documentation for the Netlify SDK and pushes it to the default branch of the netlify/developers-netlify-com repository. The workflow is triggered when a new release is pushed to the main branch.

Workflow Steps

The workflow consists of the following steps:

1. Checkout Netlify SDK: This step checks out the Netlify SDK repository to the ./netlify-sdk directory.

2. Check this is a release: This step checks if the push is a release by looking at the last commit message. If it is a release, it sets the release output to true.

3. Get GitHub App Token: This step generates a GitHub App token using the navikt/github-app-token-generator action. The token is used to authenticate with the netlify/developers-netlify-com repository.

4. Checkout Netlify SDK Docs: This step checks out the netlify/developers-netlify-com repository to the ./netlify-sdk-docs directory. It uses the GitHub App token generated in step 3 to authenticate.

5. Get SDK version: This step gets the current version of the Netlify SDK by reading the version field from the package.json file. It sets the current-version output to the SDK version.

6. Generate SDK API Reference with typedoc: This step installs the required dependencies and generates the API reference documentation using Typedoc.

7. Copy SDK API Reference to Netlify SDK Docs: This step copies the generated API reference documentation to the ./netlify-sdk-docs/src/content/docs/reference directory.

8. Push SDK API Reference to Netlify SDK Docs: This step pushes the changes to the default branch of the netlify/developers-netlify-com repository. It creates a new branch with the name update/sdk-api-reference-{SDK_VERSION} if it doesn't exist, or checks out the existing branch if it does. It then commits the changes and pushes them to the remote branch. Finally, it creates a pull request with the title "Update SDK API reference for {SDK_VERSION}" if one doesn't already exist.