There are many ways you can contribute to ink, and one of them is by helping us add more articles to our documentation! This can take the form of design guidelines, patterns, component-specific usage instructions, or accessibility guides.

Contributing to an article (or adding a new article) can be as easy as taking the time to compile your thoughts and findings, as well as any other relevant information, into a document that the ink team can use to create an article. However, it can also be a more involved process, where you are responsible for writing the article from start to finish.

Guides and patterns

Guides and patterns are documents that are written specifically for our documentation. They can be about anything related to ink or design at Carta!

Guides can range in topic from Email Kit instructions, to Carta copywriting guidelines, to the article you're reading right now! Anything related to the ink design system or design at Carta is fair game. Patterns, on the other hand, are like guides but more focused on how to use a set of components, like Form components.

Don't know how to code?

If you don't have access to GitHub or don't know your way through a code editor, you can partner with an ink team member and give your contribution through documentation in any form such as Google Docs or Figma.

Know how to code?

If you are familiar with GitHub, you can contribute directly to ink by adding your contribution yourself following these steps:

How to add a guide or pattern to the code?

Clone ink into your machine and run the documentation locally, you can follow the steps on Adding Code to ink followed by Docs Environment.
After you have the ink documents running locally you can find the patterns and guides at docs/src/content/
Select the one that better fits your intended contribution and in that folder, create the mdx file and give it a name.
Important! The name you give your file will become the url for it, so if you create a guide named adding-glitter.mdx, the url to that guide will be https://ink.carta.com/guides/adding-glitter. So be mindful of your files' names.

In the file, add a frontmatter to the very first lines, like this:

---
title: Adding guides and other articles
subtitle: How to contribute articles to the ink documentation
---

This information will be used to create the heading of your article's page:

All articles in ink are written using Markdown or MarkdownX. The latter being the one that allows for jsx to be directly written for the component to be displayed in the article.

Add your content
After you're finished, follow the opening a PR step by step to learn the best way to open a PR in ink.

What can you add to your guides and patterns?

In our docs we have a few pre-designed elements that you can use to better structure your examples.

Adding ink components to your article

So for example if you want to display an ink component to exemplify your point, instead of creating the examples in a playroom and adding the screen shots to the article, you can create the components directly inside the Markdown.

This not only helps us maintain our examples with the latest visuals, it also makes the whole process lighter and easier.

So, if you want to show a button as an example you can write in your Markdown:

JSX	Output
`<Button type="primary">Click me</Button>`

Note: At the moment, children components are not working in Markdown, so components like NewTable.Twiddle or NewFormSection.Title won't work.

Dos & Don't

The preferred way in ink to better display examples is to have two or more contrasting examples: Dos and Don'ts. To do that and make the examples even more understandable to the user, you can use the Diff and Example tags.

To build these examples you need to use:

<Diff>
  <Example type="negative" caption="Use placeholder in the input">
    <NewInput placeholder="email" />
  </Example>
  <Example type="positive" caption="Add a label using the Field component">
    <Field isStacked label="Email" htmlFor="example-input-id">
      <NewInput id="example-input-id" />
    </Field>
  </Example>
</Diff>

The end result will be:

Don't

Use placeholder in the input

Add a label using a Field

Don't

Use placeholder in the input

Add a label using a Field

Adding images

To add images to your article in order to better illustrate your point, you can add them in a folder with the name of your article inside the images folder on the respective parent folder: guides or patterns:

docs
└── content
     └── guides
          └── images
               └── your-article
                     └── image

Components' usage and accessibility guides

We also have in our documentation component specific articles that talk about specificities of the usage and accessibility of each component.

These articles live inside the component folder itself but are displayed through the documentation.

There is an accessibility tab in each component:

This tab is where all the component specific accessibility information should live.

Don't know how to code?

If you don't know how to code but want to help anyways, we currently have a document where you can help us find out documentation about accessibility for each kind of component. Reach out to the #ink channel or any individual ink team member to understand how to you can better help with this.

Know how to code?

On the other hand, if you're someone that knows your ways through code:

Clone ink into your machine
Run the documentation locally
Find the component documentation in the ./src/components/ folder.
In the component folder you should find a ComponentName.md file that represents the component's usage guide and an accessibility.md file that represents the component's accessibility guide.
Note: If the accessibility.md file doesn't exist for the component you wish to add accessibility information to, feel free to add the file. If you add it with the correct name: accessibility.md, everything should run smoothly.
Differently from the guides and patterns, these files don't accept direct jsx because they are just mds. So, if you need to add code, it needs to be through using:
```
```jsx
{/* your code here */}
```
```
Here is the Markdown guide for reference.
After you're happy with your changes follow the opening a PR article to learn the best way to open a PR in the ink repository.

Running the scrape

When you add articles to the main ink repository, which this is case here, you need to pass these articles into the documentation somehow. For that, you need to run the scrape.

The scrape is a script that gets each component's md files and parses them into several json files that are fed to the documentation folder.

Whenever you make changes, if you want to see them live in your localhost documentation you need to run yarn scrape at the root directory.