SDK Docs

This is the Netlify SDK Docs project. It contains information on anything connected to the Netlify SDK.

Table of Contents

• Stack
  • Astro & Starlight
  • Prose linting with Vale
  • Linting
  • Search
  • Analytics
  • Styling
• Support
• Default branch
• Contributing
  • Development process
• Info for tech writers
  • Update docs content
  • Add docs content
    • Add a page to an existing section
    • Add a new section
    • Adding a child page to a section
    • Add a page or section to the left sidebar
    • Nesting pages
  • Frontmatter in markdown
  • Using custom components
    • Seeing the available components
  • Using snippets
• Opening a PR
• Releasing
• Versioning breaking changes

Stack

Astro & Starlight

This project is made using Astro and the Starlight 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.

Prose linting with Vale

This repo has a GitHub action that runs Vale prose linting rules from a central shared library. Visit the netlify/vale-library repo README 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 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 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 and/or Starlight specific styling.

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 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 as its package manager.

Run:

pnpm install

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

netlify login

Check the SAML option and authorize.

Once logged in to the CLI, run:

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.

netlify build

After building, you can run the server.

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:

---
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 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:

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 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:

    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:

---
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:

---
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, go to the build you want to deploy and click Publish Deploy.

Versioning breaking changes

Until official support for versioned docs 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.