This is the Netlify SDK Docs project. It contains information on anything connected to the [Netlify SDK](https://github.com/netlify/sdk).
This is the Netlify SDK Docs project. It contains information on anything connected to the Netlify SDK.
- 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
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.
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.
Eslint and Prettier are used for code-linting purposes.
Starlight's search is powered by https://pagefind.app/.
This project is using a Google Tag Manager.
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.
For support or inquiries, please reach out through the #pod-composable-tooling slack channel.
Currently the main branch is considered the default branch for this repository. Any updates you want to make have to point to that branch.
🎉 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.
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:
``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
This part of the README is for anyone updating content inside this project.
For an update to an existing page in the docs project, locate the associated markdown file in the docs directory and edit the 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 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 for more information.
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
---
Warning!!! Learn more about code in the docs or from an external
link like this
`
#### 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.
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.
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!
`
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.
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.
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.
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.v2
- 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 branch so it will be deployed.v2` branch.
- From the new production branch, inside the sidebar to the left, add an item that points to the url of the