Contributing

How to contribute

You can help improve our guides or the API reference by making them more coherent, consistent, or readable, adding missing information, correcting factual errors, fixing typos, or bringing them up to date with the latest 128T software.

The 128 Technology documentation website is built using Docusaurus 3 to generate its static content from markdown documents. When editing existing content, or authoring new content, it is best to learn from what already exists - these are the best examples. If you are looking to learn markdown or expand on your knowledge, the GitHub-flavored Markdown syntax reference is a great resource.

Technical writing is different from other styles of writing. Markus Kazmierczak offers some great tips for how to write copy that is easy to follow where you learn as you go in his blog. We do our best to follow these principles throughout our documentation.

Testing

Before posting a PR for submitting changes, it is best to first test your changes locally to ensure that all links, references and formatting appear the way you expect. Have a look at the README for instructions on how to test locally.

Submitting Changes

1. Create a branch (typically based off of master) on the docs GitHub page.
2. On the machine where you are making your changes locally, update your repo to get the branch you just created.

   git fetch origin

3. Checkout the branch you just created

   git checkout <branch>

4. Make your changes.
5. Commit your changes.

   $ git commit -m "A brief summary of the commit
   >
   > A paragraph describing what changed and its impact."

6. Push your changes upstream

   git push origin <branch>

7. Open a Pull Request from your branch with a clear list of what you've done. Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:
8. Once the PR has been merged, the branch will be automatically deleted from origin (online). It is likely that you no longer need your local branch anymore. Remove your local branch:

   git branch -d <branch>

Issues

Did you find something wrong?

Did you find a typo or something that was incorrect and do not have the time to submit a PR yourself? Do you have suggestions for new content? That's okay, we'll get to it. Have a look at our Issues page first to see if someone else has already reported the same issue. When filling out an issue, please do your best to provide as much detail as possible. We want to make sure that we are providing the highest quality documentation to you as possible.

Did you write your own patch and want to submit the changes?

• Open a new pull request with the patch.
• Ensure the PR description clearly describes the changes as accurately as possible.
• Your changes will be merged in and published once they have been reviewed and passes all CI tests.

Guidelines

Hyperlinks

Docusaurus is particular about how links are defined within markdown in order to provide support for most browsers. While multiple formats are allowed, in practice only one approach has proven to provide the best results.

• External links require a full URL, including the scheme. [External Link](https://github.com/128technology/docs/pulls)
• Links to images, or other static content start with an exclamation point ! and require a relative path within the static directory. ![Image Description](/img/some_image.png)
• Links to resources within the site must contain the markdown file's extension (most often this is .md, but sometimes can be .mdx). [link to another file](another_file.md)
• Links to headers within the same file should contain a reference to the header only. [header link](#internal-header)
  tip

  Header links can be tricky to determine as Docusaurus removes case and adds hyphens instead of special characters. Click on the header you are interested in linking. Go to the browser URL and copy the value and paste it into your markdown file.

• Links to headers within another file require both the file name and extension, plus the header. [Link to a header within another file](another_file.md#header)

Datamodel References

When referring to paths in datamodel hierarchies, it is preferable to use a single right angle bracket to separate levels in the path. For example: authority > router > system > ntp. Even though router is a multi-instance leaf node in YANG and technically requires a key to refer to a specific instance, the instance ID is left out for brevity.

• When referring to specific instances of a configuration value, the object in discussion should be called out as code by using backticks (e.g. service-policy)
• When referring to a data model concept, it should be called in italicized format (e.g. service-policy)

Markdown Headers

The right-hand table of contents is generated from ## heading 2 and ### heading 3. Headings # heading 1 or #### header 4 and higher are excluded. Keep this in mind when organizing your content. Use this to your advantage in how you want information to appear.

Sensitive Data

When creating examples, make certain to scrub any personally identifiable information and sensitive data.

• Do not refer to actual customers or use their configuration.
• Do not include customer IP address information.

Style Guide

A style guide contains a set of standards for writing and designing content. It helps maintain a consistent style, voice, and tone across your documentation, whether you’re a lone writer or part of a huge docs team. A style guide saves documentarians time and trouble by providing a single reference for writing about common topics, features, and more. It can provide guidelines for different documentation deliverables, such as API reference manuals, tutorials, release notes, or overviews of complex technical concepts.

A consistent tone and style makes your content easier to read, reducing your users’ cognitive load and increasing their confidence in the content’s authority.

Yes	No
metadata	meta data
data center	datacenter
plugin	plug-in
internet	Internet
SSR	SSR Router
conductor	Conductor
third-party	3rd party

Callouts/admonitions

In addition to the basic Markdown syntax, Docusaurus 3 includes built-in support for admonitions (no third-party plugins required). See the official Docusaurus admonitions documentation for the full reference. Admonitions are wrapped by a set of 3 colons.

The built-in types are note, tip, info, warning, and danger. caution is also accepted as an alias for warning.

Example:

:::note
The content and title *can* include markdown.
:::

:::tip[You can specify an optional title]
Heads up! Here's a pro-tip.
:::

:::info
Useful information.
:::

:::caution
Warning! You better pay attention!
:::

:::danger
Danger danger, mayday!
:::

note

The content and title can include markdown.

You can specify an optional title

Heads up! Here's a pro-tip.

info

Useful information.

caution

Warning! You better pay attention!

danger

Danger danger, mayday!

Sidebar

The content listed in the left-hand table of contents is not automatically generated and is governed by the file sidebars.js. If you are adding new files, be sure to add it to this file as well. Release notes should always be ordered from newest to oldest.

File Naming Conventions

New files should follow the established prefix convention so they are easy to locate and categorize:

Prefix	Content type
config_	Configuration how-to guides
concepts_	Conceptual and reference topics
bcp_	Best practices
ts_	Troubleshooting
howto_	Step-by-step procedural guides
intro_	Installation and getting-started topics
cc_fips_	Common Criteria / FIPS compliance content
sec_ / sec-	Security feature guides
release_notes_	Release notes
_filename	Partial files (leading underscore = shared include, not a standalone page — do not add to sidebars.js)

Front Matter

Every .md / .mdx file should begin with a YAML front matter block. The most commonly used fields are:

---
title: Full display title (shown as H1 and in the browser tab)
sidebar_label: Shorter label used in the sidebar (optional — defaults to title)
---

Avoiding a custom id: field is preferred; Docusaurus derives the slug automatically from the filename.

Partial / Include Files

Files whose names begin with an underscore (e.g., _install_prereqs.md) are shared partials. They are imported into one or more pages using MDX import syntax and are never rendered as standalone pages. Do not add partial files to sidebars.js.

Example of importing a partial:

import InstallPrereqs from './_install_prereqs.md';

<InstallPrereqs />

Code Blocks

Always specify a language identifier on fenced code blocks to enable syntax highlighting:

```bash
systemctl restart 128T
```

Common language identifiers used in this repo: bash, json, yaml, text, jsx.

Mermaid Diagrams

Mermaid is supported natively. Use it for network topology diagrams, flowcharts, and sequence diagrams directly in markdown:

```mermaid
graph LR
  A[Conductor] --> B[Router]
```

See the Mermaid syntax reference for available diagram types.

MDX Components (Tabs)

Docusaurus ships a <Tabs> component that is useful for presenting platform-specific or alternative instructions side by side. Import it at the top of any .mdx file:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="conductor" label="Conductor-managed">Content for Conductor-managed deployments.</TabItem>
  <TabItem value="mist" label="Mist-managed">Content for Mist-managed deployments.</TabItem>
</Tabs>

Pre-PR Checklist

Before opening a pull request, verify the following:

• The local Docusaurus dev server renders your page without errors (docker-compose up)
• No broken links (npm run check-links)
• No spelling errors (codespell docs/your_file.md)
• New files are added to sidebars.js (unless they are partials)
• All images referenced in the file exist under static/img/
• Sensitive data (customer IPs, hostnames, credentials) has been scrubbed