npm package: @netlify/sdk--documentation-site
Description: This is the Netlify SDK Docs project. It contains information on anything connected to the [Netlify SDK](https://github.com/netlify/sdk).
Latest version: 0.0.1

# SDK Docs

This is the Netlify SDK Docs project. It contains information on anything connected to the [Netlify SDK](https://github.com/netlify/sdk).

## Table of Contents

- [Stack](#stack)
  - [Astro & Starlight](#astro--starlight)
  - [Prose linting with Vale](#prose-linting-with-vale)
  - [Linting](#linting)
  - [Search](#search)
  - [Analytics](#analytics)
  - [Styling](#styling)
- [Support](#support)
- [Default branch](#default-branch)
- [Contributing](#contributing)
  - [Development process](#development-process)
- [Info for tech writers](#info-for-tech-writers)
  - [Update docs content](#update-docs-content)
  - [Add docs content](#add-docs-content)
    - [Add a page to an existing section](#add-a-page-to-an-existing-section)
    - [Add a new section](#add-a-new-section)
    - [Adding a child page to a section](#adding-a-child-page-to-a-section)
    - [Add a page or section to the left sidebar](#add-a-page-or-section-to-the-left-sidebar)
    - [Nesting pages](#nesting-pages)
  - [Frontmatter in markdown](#frontmatter-in-markdown)
  - [Using custom components](#using-custom-components)
    - [Seeing the available components](#seeing-the-available-components)
  - [Using snippets](#using-snippets)
- [Opening a PR](#opening-a-pr)
- [Releasing](#releasing)
- [Versioning breaking changes](#versioning-breaking-changes)

## Stack

### Astro & Starlight

This project is made using **[Astro](https://astro.build/)** and the **[Starlight](https://starlight.astro.build/)** template with **TypeScript**. Starlight is still a work-in-progress and is being actively maintained by our partners in the Astro team. We have chosen to use Starlight because it provides a markdown-focussed and simple interface to create documentation. It has search, SEO optimisation, code highlighting, and accessibility-aware components out of the box. A note to highlight is that we are actively awaiting its future [feature to customise the layout](https://github.com/withastro/starlight/issues/415).

### Prose linting with Vale

This repo has a [GitHub action](https://github.com/netlify/sdk/.github/workflows/vale.yml) that runs **Vale** prose linting rules from a central shared library. Visit the [`netlify/vale-library` repo README](https://github.com/netlify/vale-library) to learn more. To see this linting, check out your changes in any PR.

### Linting

Eslint and Prettier are used for code-linting purposes.

### Search

**[Starlight's](https://starlight.astro.build/)** search is powered by https://pagefind.app/.

### Analytics

This project is using a Google Tag Manager.

### Styling

This project is powered with simple CSS. But due to the [current restrictions](https://github.com/withastro/starlight/issues/415) in not being able to customize components yet, it means that we currently do a lot of overriding of styles. If you want to add styling, follow these guides for [Astro specific styling](https://docs.astro.build/en/guides/styling/) and/or [Starlight specific styling](https://starlight.astro.build/guides/css-and-tailwind/).

## Support

For support or inquiries, please reach out through the `#pod-composable-tooling` slack channel.

## Default branch

Currently the `main` branch is considered the default branch for this repository. Any updates you want to make have to point to that branch.

## Contributing

🎉 Thanks for considering contributing to this project! 🎉

If your pull request is related to a typo or the documentation being unclear, please select on the relevant page’s `Edit` button (pencil icon) and directly suggest a correction instead.

Everyone is welcome regardless of personal background. We enforce a [Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and inclusive environment.

### Development process

First, clone the repository, and then change your working directory to the `docs` folder (`cd docs`). This project uses [pnpm](https://pnpm.io/) as its package manager.

Run:

```sh
pnpm install
```

To link the app to your Netlify project, using the Netlify CLI, run:

```sh
netlify login
```

Check the SAML option and authorize.

Once logged in to the CLI, run:

```sh
netlify link --id 35ffcf76-cab5-463d-a2e5-8983dba16a56
```

We use `starlightTypeDoc` to generate the reference docs for extension UI, so you need to build the SDK before you can run the docs site.

```sh
netlify build
```

After building, you can run the server.

```sh
netlify dev
```

## Info for tech writers

This part of the README is for anyone updating content inside this project.

### Update docs content

For an update to an existing page in the docs project, locate the associated markdown file in the docs directory and edit the content.

### Add docs content

Any content you add must be added to **src/content/docs**. If you add a new page anywhere, it's important that the top part of the `mdx` file contains the following frontmatter:

```mdx
---
title: Your title
layout: "@layouts/DocLayout.astro"
description: A description of the content
---
```

#### Add a page to an existing section

To add a new page to the project, create a new `mdx` file in the appropriate existing folder. Markdown file names shouldn’t include ‘stop words’ such as and, or, but, of, the, a, etc. Avoid articles, prepositions, conjunctions, pronouns, etc. Creating the file in the appropriate folder adds a page to the project but doesn't add it to the left nav bar.

#### Add a new section

For a new section, create a new folder in docs with the name of the new section and add a new markdown file. This adds the folder and page to the project but doesn't add it to the left nav bar.

```
├── new-section
│   ├──subject-title.mdx
```

#### Adding a child page to a section

If you want to add another child page to a section, add it in the same manner, in a folder in docs with the name of the section. This adds the folder and page to the project but doesn't add it to the left nav bar.

```
├── new-section
|   ├──subject-title.mdx
│   ├──child-page.mdx
```

#### Add a page or section to the left sidebar

Follow [this guide from Starlight](https://starlight.astro.build/reference/configuration/#sidebar) to add a new section or page to the left sidebar.

#### Nesting pages

It is possible to nest pages, which is not specifically documented in the Starlight docs. This is an example of different types of nesting:

```json
sidebar: [
	{ label: "External link", link: "https://answers.netlify.com/" },
	{
    label: "API Reference",
    collapsed: true,
    autogenerate: { directory: "reference" }, // automatically generates items from directory.
  },
	{
    label: "Welcome",
    items: [
      { label: "Overview", link: "overview/" }
    ],
  },
  {
    label: "Three deep",
    items: [
      {
        label: "A label",
        collapsed: true,
        items: [
          { label: "Content", link: "some-content" } // three deep
        ]
      },
    ]
  },
],
```

#### Frontmatter in markdown

There are many options available for the frontmatter in our markdown files. Check out [this guide](https://starlight.astro.build/reference/frontmatter/) for more information.

### Using custom components

It's possible to add a new component to `src/components`. Any really specific Netlify UI components are added to `src/components/ui`.

To use the component, first add it to the list of imports passed to `AutoImport` in the `astro.config.mjs` file:

```mjs
    AutoImport({
      imports: [
        "./src/components/ui/Beta.astro",
        "./src/components/ui/Panel.astro",
        {
          '@astrojs/starlight/components': ['Card', 'Tabs', 'TabItem'],
        },
      ],
    }),
```

Then, you can use the component in your `mdx` file like this:

```mdx
---
title: Samples
layout: "@layouts/DocLayout.astro"
description: Some examples of our custom components
---

## Panels

<Panel title="warning" type="warning">
  Warning!!! [Learn more about `code` in the docs](#) or from an [external
  link](https://example.com) like this
</Panel>
```

#### Seeing the available components

When running this project locally you can look at the `samples` page to see a list of currently available components. This list lives inside `src/content/docs/samples`.

## Opening a PR

Awesome! Please open a PR that points to the `main` branch in this repository. In that PR, please do the following:

1. Make your documentation changes
2. Open a PR
3. In your PR assign the right people for a review. For frontend changes make sure to ask pod-composable-tooling for feedback, for content changes make sure to include someone from the docs team as well.

### Using snippets

Have you got content that keeps repeating in different places? Consider using a snippet! A snippet can be made by adding an `mdx` file in `src/snippets/` and importing it like so:

```mdx
---
title: Fake title
layout: "@layouts/DocLayout.astro"
description: Fake description!
---

import Hi from "src/snippets/hi.md";

This is the normal content!

<Hi />
```

## Releasing

Any time you merge a new change into `main`, Netlify will build a new version of this project. To publish a new version of the SDK docs, you can [go into the Netlify UI](https://app.netlify.com/projects/sdk/deploys), go to the build you want to deploy and click `Publish Deploy`.

## Versioning breaking changes

Until [official support for versioned docs](https://github.com/withastro/starlight/issues/372) is supported we have a strategy in place for the way we want to version our docs in case of breaking changes after v1.

### v1 to v2: inline changes

If we notice that the differences between v1 and v2 are not a huge change, we'll take the approach of adding inline code examples together with warnings. We also strongly believe in adding a migration guide in the sidebar called "Migrate from v1 to v2" that walks the user through any breaking changes, and how to migrate those. We reference to this migration guide from the release notes.

Some examples of how to show these changes in-line can be found in `src/content/docs/examples/usecases.mdx`.

### v2 to v3 and beyond - versioned deploys

Inline-related versions may become difficult to maintain in the long-run. What if we are 3 versions in, how can we refer back to older ones? This is why we want to create a branch deploy to old versions of the docs, together with making it visually super clear to the visitor that they are looking at old docs.

#### How-to:

- Before making updating the docs to the v3 version (or beyond), make an official `v2` branch in the project.
- On this branch, make it visually clear that users are looking at an old version of the SDK docs.
- Create a visually clear link to the production deploy of the docs, to point them to the latest version of the docs.
- Protect this branch in GitHub.
- Set up branch deploys for this `v2` branch so it will be deployed.
- From the new production branch, inside the sidebar to the left, add an item that points to the url of the `v2` branch.