Netlify SDK

SDK for developing integrations on Netlify.

Documentation

The documentation lives in https://sdk.netlify.com If you want to edit the documentation, you can do so in the docs folder in this monorepository.

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.