Contributing

This documentation site is a living entity, growing and improving alongside StrataKit itself. You may find some information missing, unclear, superfluous, or in the wrong place. That’s where you can help.

Please follow the contribution instructions below. If you try to contribute via other channels or using different software, we will not be able to properly track, review, and publish your work.

“Edit page”

At the foot of every page, you’ll find a link labeled ✎ Edit page. Press this link to an editable version of the page’s content on Github. Follow these steps to make your contribution:

1. Make your changes to the markdown source. See Markdown help, if you are unfamiliar with the syntax.
2. Click the Commit changes button in the top right corner of the Github interface.
3. Fill out the Propose changes dialog that appears:
   1. Commit message: Please use a short, descriptive message. What did you change?
   2. Extended description: Describe your intent. Where did the need for the edit come from?
   3. Commit email: Use your bentley.com email if it is an option.
   4. New branch name Please use the format [your username]/edit/[page title]. Example: heydon/edit/getting-started/ (since the page title uses multiple words, these are joined by a hyphen).
4. Click Propose changes at the foot of the dialog.
5. On the Open a pull request page that appears, double check the information you’ve supplied and click Create pull request when you’re happy.
6. Your pull request will need to be approved by a member of the StrataKit team. You may be asked questions in the comment stream of the pull request. Remember to check your Github notifications.
7. Thank you!

Guidance structure

Consistency supports both comprehension and navigation. Each component guide follows a common schema:

• Component name
  • Use cases: Is this, or another, component right for my use case? (compares similar components in a table)
  • Usage: How should I implement this component? With which other components? (a basic example is followed by some other cases)
  • Configurations: What options are there for changing the appearance and behavior of the component? (variants, tones, and other customization options)
  • Do: A summary of best practices and opportunities.
  • Don’t: Things to avoid for an error-free and accessible implementation.

Headings

The major sections Use cases through to Don’t must each use a level 2 heading (<h2>). See Headings for the markdown syntax. Organize subsections under these headings using <h3> and <h4> as appropriate.

Markdown help

This site’s content is written in markdown: a minimal formatting syntax using special characters. In fact, in this case it’s a special flavour of markdown with some additional options. Here is a brief guide:

Inline text styling

• bold → **bold**
• italic → _italic_
• bold and italic → **_bold and italic_**
• code → `code`
• link → [link](https://bentley.com)

Structural elements

Lists

• First list item
• Another list item
• List item number three
• The final item in the list

- First list item
- Another list item
- List item number three
- The final item in the list

Headings

Heading (level 1)

Heading (level 2)

Heading (level 3)

Heading (level 4)

# Heading (level 1)

## Heading (level 2)

### Heading (level 3)

#### Heading (level 4)

Tables

Use case	Link	Button
Navigating between interface screens or sections	✅	❌
Submitting forms, confirming or cancelling dialogs, creating or deleting content	❌	✅

| Use case                                                                         | [Link](/components/link) | [Button](/components/button) |
| -------------------------------------------------------------------------------- | ------------------------ | ---------------------------- |
| Navigating between interface screens or sections                                 | ✅                       | ❌                           |
| Submitting forms, confirming or cancelling dialogs, creating or deleting content | ❌                       | ✅                           |

Frontmatter

At the top of each markdown file is a section starting and ending with --- markers. This is the frontmatter data for the page. This data is organized into key/value pairs. For this page, the title is set using title: Contributing.

For reference, here is what the Button frontmatter looks like:

---
title: Button
description: Buttons are used to initiate actions.
links:
  muiDocs: https://mui.com/material-ui/react-button/
  apiReference: https://mui.com/material-ui/api/button/
---

• title: The main heading for the page (“Button” here)
• description: The short description/strapline following the title
• status: The current status of the component. See component status for the accepted values and their meanings.
• associated: These are any components that can be combined with the current component to make more complex patterns. This list (indented, using a - prefix for each component) must name the component exactly. See associated components for more information.
• links: A list of key/value pairs. The figma URL must point to the Figma component in the Figma component library

Asides

Occasionally, something needs to be noted but it doesn’t fit within the main flow of the document. You can interject notes (or “asides”) using a special syntax. The Starlight framework, on which these docs are based, has a guide on asides and their syntax.

Here is an example from the Switch page:

:::note[Composition]
You must use the **Switch** in conjunction with a label. See [Usage](#usage).
:::

Exercise caution

You may encounter some syntax that isn’t documented above. The rule is: if it’s not documented here, don’t try to use or edit it. If some unfamiliar syntax needs to be moved inside the document, make sure you move it in its current form, and in its entirety. Otherwise, you are liable to cause errors.