# Contributing docs and examples

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](https://www.union.ai/docs/latest/flyte/community/contributing-docs/section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

We welcome contributions to the docs and examples for both Flyte and Union.
This section explains how the docs site works and walks you through setting it up, authoring content, and submitting your changes.

## Where to start

* [Set up a local docs dev environment](https://www.union.ai/docs/latest/flyte/community/contributing-docs/quick-start/page.md): clone the repository, initialize the submodules, and run the live preview.
* [Author content](https://www.union.ai/docs/latest/flyte/community/contributing-docs/authoring/page.md): write pages with Markdown, shortcodes, and variants.
* [Writing guidelines](https://www.union.ai/docs/latest/flyte/community/contributing-docs/writing-guidelines/page.md): the editorial conventions the site follows.
* [Submit a contribution](https://www.union.ai/docs/latest/flyte/community/contributing-docs/submitting-contributions/page.md): open a pull request and get it merged.

The rest of this section is reference material: [Variants](https://www.union.ai/docs/latest/flyte/community/contributing-docs/variants/page.md), [Versions](https://www.union.ai/docs/latest/flyte/community/contributing-docs/versions/page.md), [Shortcodes](https://www.union.ai/docs/latest/flyte/community/contributing-docs/shortcodes/page.md), [API docs](https://www.union.ai/docs/latest/flyte/community/contributing-docs/api-docs/page.md), [LLM-optimized documentation](https://www.union.ai/docs/latest/flyte/community/contributing-docs/llm-docs/page.md), [Redirects](https://www.union.ai/docs/latest/flyte/community/contributing-docs/redirects/page.md), and [Production builds and troubleshooting](https://www.union.ai/docs/latest/flyte/community/contributing-docs/publishing/page.md).

## How the docs site works

As the primary maintainer and contributor of the open-source Flyte project, Union.ai hosts the Flyte documentation.
Union.ai is also the company behind the commercial Union.ai product, which is built on Flyte.

Because Flyte and Union.ai share much of their functionality, most of the documentation content is common between them.
There are, however, significant differences between Flyte and Union.ai and among the Union.ai deployment options (BYOC and Self-managed).

To maintain the documentation for all of these variants efficiently, we use a single-source-of-truth approach:

* All content is stored in a single GitHub repository, [`unionai/unionai-docs`](https://github.com/unionai/unionai-docs).
* All content is published on a single website, [`www.union.ai/docs`](https://www.union.ai/docs/v2/root/).
* A variant selector at the top of each page lets you choose which variant to view: Flyte OSS or Union.ai (which covers both BYOC and Self-managed deployments).
* A version selector lets you choose between v1 (Flyte/Union 1.x) and v2 (Flyte/Union 2.0, which you are viewing now).

### Versions

The two versions of the docs are stored in separate branches of the repository:

* The [`v1` branch](https://github.com/unionai/unionai-docs/tree/v1) holds the v1 docs.
* The [`main` branch](https://github.com/unionai/unionai-docs) holds the v2 docs.

See [Versions](https://www.union.ai/docs/latest/flyte/community/contributing-docs/versions/page.md) for details.

### Common build infrastructure

The build infrastructure (Hugo configuration, layouts, themes, build scripts, and Python tools) lives in a separate repository, [`unionai/unionai-docs-infra`](https://github.com/unionai/unionai-docs-infra), imported as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) at `unionai-docs-infra/`.

Both the `main` (v2) and `v1` content branches share this infrastructure.
Changes to the build system are made once in `unionai-docs-infra` and picked up by both branches, keeping them in sync without duplicating build logic.

### Variants

Within each branch, the variants are supported by conditional rendering:

* Each page declares which variants it applies to in its `variants` frontmatter field.
* Within a page, rendering logic includes or excludes content based on the selected variant.

The result is that content common to all variants is authored once, while variant-specific content is rendered conditionally.
See [Variants](https://www.union.ai/docs/latest/flyte/community/contributing-docs/variants/page.md) for details.

### Both Flyte and Union docs are open source

Because the docs are combined in one repository and the Flyte docs are open source, the Union docs are open source too.
Everyone can contribute: Flyte contributors, Union customers, and Union employees.

If you are a Flyte contributor, you contribute docs related to Flyte features, and in many cases those features are also available in Union.
Because the docs site is a single source for all the documentation, when you make a change related to Flyte that is also valid for Union, you do it in the same place.
This is by design and is a key feature of the docs site.

## Subpages

- [Set up a local docs dev environment](https://www.union.ai/docs/latest/flyte/community/contributing-docs/quick-start/page.md)
  - Prerequisites
  - Clone the repository
  - Initialize the submodules
  - Configure the live preview
  - Start the live preview
  - Development settings
  - Build the production site
  - Next steps
- [Authoring](https://www.union.ai/docs/latest/flyte/community/contributing-docs/authoring/page.md)
  - Getting started
  - Live preview
  - Page visibility
  - Page order
  - Page settings
  - Conditional content
  - Linking to the API reference
  - Sigils for special cases
  - Warnings and notices
  - Special content generation
  - Python generated content
  - Run on Union instructions
  - Jupyter notebooks
  - Mapped keys (`{{</* key */>}}`)
  - Mermaid graphs
- [Submit a contribution](https://www.union.ai/docs/latest/flyte/community/contributing-docs/submitting-contributions/page.md)
  - Target the right branch
  - Fork and clone
  - Create a feature branch
  - Make and preview your changes
  - Commit with a sign-off
  - Open a pull request
  - Check the preview build
  - Review and merge
- [Writing guidelines](https://www.union.ai/docs/latest/flyte/community/contributing-docs/writing-guidelines/page.md)
  - Lead with the task
  - Write in a clear, active voice
  - Structure a page
  - Use sentence case for headings
  - Use notes and warnings deliberately
  - Keep terminology consistent
  - Make examples runnable and tested
  - Link to the API reference by writing the identifier
- [Variants](https://www.union.ai/docs/latest/flyte/community/contributing-docs/variants/page.md)
  - Variants at the whole-page level
  - Conditional rendering within a page
  - {{</* variant */>}}
  - {{</* key */>}}
  - Full example
  - Adding a new variant
  - Location
  - Creating a new variant
  - Testing the new variant
  - Building (just) the variant
- [Versions](https://www.union.ai/docs/latest/flyte/community/contributing-docs/versions/page.md)
  - What a version contains (and what it does not)
  - Versions are branches
  - How to create an archive version
  - How to create an archive version
  - Publishing an archive version
- [Shortcodes](https://www.union.ai/docs/latest/flyte/community/contributing-docs/shortcodes/page.md)
  - How to specify a "shortcode"
  - Variants
  - Component library
  - `{{</* audio */>}}`
  - `{{</* grid */>}}`
  - `{{</* variant */>}}`
  - `{{</* link-card */>}}`
  - `{{</* markdown */>}}`
  - `{{</* multiline */>}}`
  - `{{</* tabs */>}}` and `{{</* tab */>}}`
  - `{{</* key */>}}`
  - `{{</* download */>}}`
  - `{{</* docs_home */>}}`
  - `{{</* py_class_docsum */>}}`, `{{</* py_class_ref */>}}`, and `{{</* py_func_ref */>}}`
  - `{{</* icon name */>}}`
  - `{{</* code */>}}`
- [API docs](https://www.union.ai/docs/latest/flyte/community/contributing-docs/api-docs/page.md)
  - API naming convention
  - Package resource resolution
  - Tips and tricks
  - Auto-linking
  - Short vs. fully-qualified names
  - How auto-linking works
  - Magic-marker syntax for inline code
- [LLM-optimized documentation](https://www.union.ai/docs/latest/flyte/community/contributing-docs/llm-docs/page.md)
  - Output files
  - Discovery hierarchy
  - How `page.md` files are generated
  - Enabling section bundles
  - The `llms-full.txt` link conversion
  - Regenerating
- [Redirects](https://www.union.ai/docs/latest/flyte/community/contributing-docs/redirects/page.md)
  - `docs.union.ai` redirects
  - `docs.flyte.org` redirects
- [Production builds and troubleshooting](https://www.union.ai/docs/latest/flyte/community/contributing-docs/publishing/page.md)
  - Build the production site
  - Test the production build
  - Troubleshooting
  - Missing content
  - Page visibility

---
**Source**: https://github.com/unionai/unionai-docs/blob/main/content/community/contributing-docs/_index.md
**HTML**: https://www.union.ai/docs/latest/flyte/community/contributing-docs/