Skip to content

Contributor Guide and Template Updates #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
owilliams320 merged 3 commits into from
Feb 4, 2026
Merged

Contributor Guide and Template Updates #208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7d3e212
Update README with more contributor details
brendon-paucek Feb 2, 2026
4c30971
Create an initial page template
brendon-paucek Feb 2, 2026
d72ab94
Workspace settings.json update for internal link assistance
brendon-paucek Feb 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .vscode/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
{}
{
"markdown.updateLinksOnFileMove.enabled": "prompt"
}
228 changes: 182 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,86 +1,222 @@
# Teradata Developer Resources

[Developer resources](https://developers.teradata.com/) documentation and tutorials for learning Teradata Vantage. The documents are formatted using Markdown. This documentation site is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
This repository is the home of all code and content for [developers.teradata.com](https://developers.teradata.com/).

Contributions are welcome! See below for how to build the documentation website locally.
Contributions are welcome! To get started, review the contributor guide information in this README.

### General Information
* The documentation in this repository uses Markdown syntax. If you're unfamiliar with Markdown, please check out this [guide](https://www.markdownguide.org/).
* The `main` branch is the default branch and reflects what’s currently on the [website](https://developers.teradata.com/). Each commit made to the `main` branch will trigger a new deployment to GitHub Pages.
* Simple content changes can be made through a pull request directly from GitHub's website. For larger changes, such as reformatting or adding a new page, we recommend forking the repo, cloning it locally, and following the instructions on how to build the website locally.
* Each page corresponds to a Markdown file in the repository. Pages are located in the `quickstarts` or `docs` directories. Page files must have a `.md` or `.mdx` suffix if using React components.
* This guide explains how to run and build [Docusaurus](https://docusaurus.io/docs/installation#running-the-development-server) locally to test changes before submitting a pull request.
## Project Overview

- This site is built using [Docusaurus](https://docusaurus.io/docs/) and uses markdown syntax in MDX.
- The `main` branch is the default branch and reflects what’s currently published. Committing or merging a branch into `main` automatically triggers a web site update.
- Contributors can submit simple content changes via pull request directly to the repo in [GitHub](https://github.com/Teradata/developer-resources). For larger changes, such as reformatting or adding a new page, Teradata recommends forking the repo, cloning it locally, and following the instructions on how to build the website locally before submitting a pull request.
- Each page corresponds to a Markdown file in the repository. Pages are located in the docs or quickstarts directories. Page files must have a `.md` or `.mdx` suffix if using React components.

## Content Directories

| Directory | Description | Sidebar Configuration |
| -------------------------- | -------------------------------------------------- | -------------------------------------- |
| [docs](docs) | Primary location for documentation pages main site | Metadata-driven with `index.md` |
| [quickstarts](quickstarts) | Quickstart guides and introductory workflows | Metadata-driven with `_category_.json` |

---

# Contributor's Guide for Docusaurus
## Contributor's Guide for Docusaurus

Thank you for your interest in contributing to [developers.teradata.com](https://developers.teradata.com/) project. Your contributions help improve and expand the resources available to the community.

> **Templates:**
> See the [templates](templates) directory for page examples, markdown syntax examples, and sidebar configuration explanations.

### Contributor Requirements

- Familiarity with MDX markdown syntax. To learn more, see the [MDX](https://mdxjs.com/) web site.
- Familarity with GitHub and simple git branching principles. Teradata recommends installing [GitHub Desktop](https://desktop.github.com/download/) to help manage branch activity and to clone the repository.
- Teradata recommends using [VS Code](https://code.visualstudio.com/) with these extensions:
- [Docusaurus MDX Previewer](https://marketplace.visualstudio.com/items?itemName=mileskies.docusaurus-mdx-previewer)
- [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
- `npm` installed for developer dependencies and building the site locally. For non-technical contributors, download and install `npm` for your operating system from the the [node.js](https://nodejs.org/en/download) web site.

Thank you for your interest in contributing to our developer resources project. Your contributions help improve and expand the resources available to the community. This guide will help you get started with contributing to our repository.
### Modify an Existing Page

## General Information
We appreciate all contributions, whether they are bug reports, feature requests, or documentation improvements. Please follow the guidelines below to ensure a smooth contribution process.
1. Navigate to the [docs](docs) or [quickstarts](quickstarts) folder in your project directory. Each MDX file corresponds to a page on the documentation site.
1. Open the relevant file and make edits. Docusaurus supports Markdown with JSX extensions, allowing you to easily add React components if needed.

## Modify an Existing Page
To modify an existing page, follow these steps:
1. Navigate to the `docs` or `quickstarts` folder in your project directory, where you'll find the Markdown files corresponding to your site's pages.
2. Open the relevant file and make the necessary edits. Docusaurus supports Markdown with JSX extensions, allowing you to easily add React components if needed.
3. Preview your changes by running `npm start` for a local development server. If you're already running the server, the site will automatically rebuild with the updated content.
4. Commit your changes to a new branch and submit a pull request.
### Add a New Page

## Add a New Page
To add a new page, follow these steps:
1. Create a new Markdown file in the appropriate directory under `docs` or `quickstarts`.
2. Add the necessary content to the Markdown file. Use this helpful [guide](https://docusaurus.io/docs/create-doc) and the [Docusaurus feature reference](https://docusaurus.io/docs/markdown-features) to assist in creating a new document.
3. Preview your changes by running `npm start` for a local development server. If the server is already running, the site will automatically rebuild with the updated content.
4. Commit your changes to a new branch and submit a pull request.
1. Create a new Markdown file in the appropriate directory under [docs](docs) or [quickstarts](quickstarts).
1. Add the necessary content to the Markdown file. Use this helpful [guide](https://docusaurus.io/docs/create-doc) and the [Docusaurus feature reference](https://docusaurus.io/docs/markdown-features) to assist in creating a new document.

## Add an Image or Attachment
To add an image or any file attachment, follow these steps:
### Reusing Content

### Step 1: Place the Asset in the Static Folder
Docusaurus uses `_partials` to store snippets of markdown content for reuse.

> **Best Practice**: To maximize reusability, reusable content should be relativetly short and discrete.

1. In a `_partials` directory, create a Markdown file to store your snippet of content.
1. In the Markdown file, use the following syntax to relative reference to it:

```
import MyPartial from '../_partials/example-partial-path.md';
```

### Add an Image or Attachment

Docusaurus uses a `static` folder where you can place static assets such as images, videos, or files. Any file placed in this folder is automatically available at the root URL.

1. Inside your Docusaurus project, navigate to the `static` folder.
2. Create a subfolder inside `static` for organization, e.g., `img` or `files`, to store your images or files.
3. Place your image or file in this folder, e.g., `static/img/my-image.png`.

### Step 2: Use the Asset in a Markdown File
1. Create a subfolder inside `static` for organization, e.g., `img` or `files`, to store your images or files.
1. Place your image or file in this folder, e.g., `static/img/my-image.png`.

Once your asset is in the `static` folder, you can reference it in your Markdown files using a relative path.

```markdown
![My Image Description](./img/my-image.png)
```

### Tips:
- Always place your images in the `static` folder to ensure Docusaurus correctly handles the image path.
- Use relative paths to link images, starting with `/`, e.g., `/img/my-image.png`.
> **Tips**
>
> - Always place your images in the `static` folder to ensure Docusaurus correctly handles the image path.
> - Use relative paths to link images, starting with `/`, e.g., `/img/my-image.png`.

### Preview Your Changes Locally

1. Use the Docusaurus MDX previewer extension to preview an individual page.
1. To preview the entire site with your changes and to validate your change, run `npm start` from the repository root for a local development server. If the server is already running, the site will automatically rebuild with the updated content.

## How to Avoid Duplicating Content

To avoid duplicating content, follow these guidelines:

1. Search the repository to check if the content already exists.
2. If similar content exists, consider updating the existing content instead of creating new content.
3. Coordinate with other contributors to ensure consistency and avoid duplication.
1. If similar content exists, consider updating the existing content instead of creating new content.
1. Coordinate with other contributors to ensure consistency and avoid duplication.

## Serve the Website Locally

To serve the website locally, follow these steps:

1. Run the development server using `npm run start`.
2. Open your browser and navigate to `http://localhost:3000`.
1. Open your browser and navigate to `http://localhost:3000`.

## Build Documentation Locally

To build the documentation locally, follow these steps:

1. Clone the repository to your local machine.
2. Install the necessary dependencies using `npm install`.
3. Build the documentation using `npm run build`.
4. Preview the static build by running `cd build && npx http-server`.
1. Install the necessary dependencies using `npm install`.
1. Build the documentation using `npm run build`.
1. Preview the static build by running `cd build && npx http-server`.

## Best Practices

To ensure high-quality contributions and maintain consistency across the project, please follow these best practices:

1. **Use Clear and Concise Language**: Write clearly and concisely to make the documentation easy to understand.
2. **Follow Markdown Standards**: Use standard Markdown syntax and conventions to ensure consistency across all documents.
3. **Keep It Simple**: Avoid overly complex explanations and technical jargon where possible. Aim to make the documentation accessible to a wide audience.
4. **Use Proper Formatting**: Use headings, lists, and code blocks appropriately to organize content and improve readability.
5. **Provide Examples**: Include examples and code snippets to illustrate concepts and make the documentation more practical.
6. **Review and Edit**: Before submitting a pull request, review your changes for accuracy, clarity, and completeness. Edit as needed to ensure high quality.
7. **Collaborate and Communicate**: Engage with other contributors and maintainers through comments, discussions, and reviews to ensure alignment and address any issues.
1. **Follow Markdown Standards**: Use standard Markdown syntax and conventions to ensure consistency across all documents.
1. **Keep It Simple**: Avoid overly complex explanations and technical jargon where possible. Aim to make the documentation accessible to a wide audience.
1. **Use Proper Formatting**: Use headings, lists, and code blocks appropriately to organize content and improve readability.
1. **Provide Examples**: Include examples and code snippets to illustrate concepts and make the documentation more practical.
1. **Review and Edit**: Before submitting a pull request, review your changes for accuracy, clarity, and completeness. Edit as needed to ensure high quality.
1. **Collaborate and Communicate**: Engage with other contributors and maintainers through comments, discussions, and reviews to ensure alignment and address any issues.

---

## TOC Generation

Sidebar placement and TOC building is metadata-driven. Two different implementations are currently in effect between the [docs](../docs) and [quickstarts](../quickstarts) directories.

> TOCs are generally managed by Teradata content architects and repo admins, who may modify sidebar metadata of any contributor pull requests.

### docs directory

- Each sub-directory is a section.
- `index.md` is the parent page of a directory, and the `sidebar_position` in an `index.md` determines the the ordering of entire sections relative to other `index.md` files.
- All other `.md` files are nested under the `index.md` file in the same directory based on its position.
- The same principles apply to directories further nested in a directory, but nesting deeper than two levels deep in a given sidebar is not recommended.

```
docs/
├── Section A / <-- Appears FIRST (Position 1)
│ ├── index.md ---
│ │ sidebar_position: 1
│ │ ---
│ └── child_page.md
│
├── Section B / <-- Appears SECOND (Position 2)
│ ├── index.md ---
│ │ sidebar_position: 2
│ │ ---
│ └── child_page.md
│
└── Section C / <-- Appears THIRD (Position 3)
├── index.md ---
│ sidebar_position: 3
│ ---
└── child_page.md
```

The result would look like this:

```
Section A (content of index.md)
Child (content of position 1)
Child (content of position 2)
Section B (content of index.md)
Child (content of position 1)
Child (content of position 2)
Section C (content of index.md)
Child (content of position 1)
Child (content of position 2)
```



### quickstart directory

The quickstarts uses the Docusaurus `_category_.json` method. In lieu of using `index.md` parent pages with content in a given sub-directory, the JSON files define the order of sub-directories relative to each other in the same way. The result is an expander title in the sidebar that does not equate to a page URL and content.

```JSON
{
"label": "Title in Sidebar",
"position": 1
}
```

In each sub-directory each `.md` still includes a `sidebar_position` metadata attribute that defines order within the sub-directory.


```
docs/
├── Section A / <-- Appears FIRST (Position 1)
│ ├── _category_.json ---
│ │ sidebar_position: 1
│ │ ---
│ └── child_page.md
│
├── Section B / <-- Appears SECOND (Position 2)
│ ├── _category_.json ---
│ │ sidebar_position: 2
│ │ ---
│ └── child_page.md
│
└── Section C / <-- Appears THIRD (Position 3)
├── _category_.json ---
│ sidebar_position: 3
│ ---
└── child_page.md
```

The result would look like this:

```
Section A (sidebar only - no content)
Child (content of position 1)
Child (content of position 2)
Section B (sidebar only - no content)
Child (content of position 1)
Child (content of position 2)
Section C (sidebar only - no content)
Child (content of position 1)
Child (content of position 2)
```
92 changes: 92 additions & 0 deletions templates/general_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
# Page metadata
id: # page-slug-url
title: # Full Page Title
description: # Short description of the page content
sidebar_label: # Optional shortened version of title for the TOC
sidebar_position: # Numerical value for TOC placement.
pagination_prev: null # Disables page nav arrows
pagination_next: null # Disables page nav arrows
---

# General Topic Template

This topic includes various markdown formatting examples to help contributors create content.

## Subheaders

Subheaders should not skip sequence. In other words, do not skip from an `## H2` to an `#### H4` without using an `### H3` first. Generally, a single topic should not nest content deeper than an `## H2` or `### H3`.

## Notes

Notes syntax varies throughout Markdown implementations, and Docusaurus is no exception by using colons `:::`.

:::note
All note blocks are wrapped with three colons `:::`.

:::tip
Note types include tips for helping users identify best practices or advice targeted to a specific persona.
:::

:::important
Important notes highlight caution about important actions or consequences of an action.
:::

## Tables

Docusaurus supports standard markdown tables. For advanced formatting, see the Docusaurus documentation and test locally. Teradata recommends keeping tables simple and scannable. Use tables for reference-heavy content. Avoid long paragraphs and nesting other block-level elements within tables.

| Header 1 | Header 2 | Header 3 |
| ------------ | ------------ | ------------ |
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |
| Row 3, Col 1 | Row 3, Col 2 | Row 3, Col 3 |

## Lists

Use unordered lists to organize content and make it scannable. You can use `-` or `*` but Teradata recommends `-`.

- List item
- List item

Use ordered lists for steps within a task or describing things that happen in a sequence. Use `1.` for each item and let the markdown processing dynamically render the number at build time.

1. Step one.
1. Step two.

Each list item in a given list should be written the same way (e.g., paralellism).

## Code blocks

Code blocks follow standard markdown syntax. Wrap the codeblock in three ticks and a language designation.

Here's the example page metadata that uses a yaml header.

```yaml
---
id: general-topic-template
title: General Topic Template
description: A template page with structure and markdown help for contributors
sidebar_label: General Template
sidebar_position: 1
pagination_prev: null
pagination_next: null
---
```

Other common languages may include python, JSON, and bash.

## Links

Links use standard markdown syntax: `[Text](PATH)`

| Link type | Syntax | Notes |
| --------- | -------------------------------------------------- | ------------------------------------------------------------------ |
| External | [Teradata Documentation](http://docs.teradata.com) | Use for any link to public content not on developers.teradata.com |
| Internal | [README](../README.md) | Use relative links for all references to content within this repo. |

## In-line Syntax

Use **bold** for any UI elements that users interact with, such as buttons that users click or windows and panes that users can open and see. Avoid using it just for emphasis.

Use `code` in-line code snippets, example text and variables, and CLI utility names and references.