# Contributing docs and examples

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](https://www.union.ai/docs/v2/union/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 will explain how the docs site works, how to author and build it locally, and how to publish your changes.

## The combined Flyte and Union docs site

As the primary maintainer and contributor of the open-source Flyte project, Union AI is responsible for hosting the Flyte documentation.

Additionally, Union AI is also the company behind the commercial Union.ai product, which is based on Flyte.

Since Flyte and Union.ai share a lot of common functionality, much of the documentation content is common between the two.
However, there are some significant differences between not only Flyte and Union.ai but also among the different Union.ai product offering (Serverless, BYOC, and Self-managed).

To effectively and efficiently maintain the documentation for all of these variants, we employ a single-source-of-truth approach where:

* 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/).
* The website has a variant selector at the top of the page that lets you choose which variant you want to view:
    * Flyte OSS
    * Union Serverless
    * Union BYOC
    * Union Self-managed
* There is also version selector. Currently two versions are available:
    * v1 (the original docs for Flyte/Union 1.x)
    * v2 (the new docs for Flyte/Union 2.0, which is the one you are currently viewing)

## Versions

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

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

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

## Common build infrastructure

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

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

## Variants

Within each branch the multiple variants are supported by using conditional rendering:

* Each page of content has a `variants` front matter field that specifies which variants the page is applicable to.
* Within each page, rendering logic can be used to include or exclude content based on the selected variant.

The result is that:
* Content that is common to all variants is authored and stored once.
  There is no need to keep multiple copies of the same content in-sync.
* Content specific to a variant is conditionally rendered based on the selected variant.

See [Variants](https://www.union.ai/docs/v2/union/community/contributing-docs/variants/page.md) for more details.

## Both Flyte and Union docs are open source

Since the docs are now combined in one repository, and the Flyte docs are open source, the Union docs are also open source.
All the docs are available for anyone to contribute to: Flyte contributors, Union customers, and Union employees.

If you are a Flyte contributor, you will be contributing docs related to Flyte features and functionality, but in many cases these features and functionality will also be available in Union.
Because the docs site is a single source for all the documentation, when you make changes related to Flyte that are also valid for Union you do so in the same place.
This is by design and is a key feature of the docs site.

## Subpages

- [Quick start](https://www.union.ai/docs/v2/union/community/contributing-docs/quick-start/page.md)
  - Prerequisites
  - Clone the repository
  - Live preview
  - Distribution build
- [Variants](https://www.union.ai/docs/v2/union/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/v2/union/community/contributing-docs/versions/page.md)
  - Versions are branches
  - How to create an archive version
  - How to create an archive version
  - Publishing an archive version
- [Authoring](https://www.union.ai/docs/v2/union/community/contributing-docs/authoring/page.md)
  - Getting started
  - Target the right branch
  - Live preview
  - Pull Requests + Site Preview
  - Page Visibility
  - Page order
  - Page settings
  - Conditional Content
  - Warnings and Notices
  - Special Content Generation
  - Python Generated Content
  - Run on Union Instructions
  - Jupyter Notebooks
  - Mapped Keys (`{{</* key */>}}`)
  - Mermaid Graphs
- [Shortcodes](https://www.union.ai/docs/v2/union/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 */>}}`
- [Redirects](https://www.union.ai/docs/v2/union/community/contributing-docs/redirects/page.md)
  - `docs.union.ai` redirects
  - `docs.flyte.org` redirects
- [API docs](https://www.union.ai/docs/v2/union/community/contributing-docs/api-docs/page.md)
  - API naming convention
  - Package Resource Resolution
  - Tips and Tricks
  - Enabling auto-linking for plugins
  - 1. Server-side code block linking
  - 2. Client-side inline code linking
  - How auto-linking works
- [LLM-optimized documentation](https://www.union.ai/docs/v2/union/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
- [Publishing](https://www.union.ai/docs/v2/union/community/contributing-docs/publishing/page.md)
  - Requirements
  - Managing the Tutorial Pages
  - Building and running locally
  - Developer Experience
  - Controlling Development Environment
  - Changing 'variants'
  - Troubleshootting
  - Identifying Problems: Missing Content
  - Identifying Problems: Page Visibility
  - Building Production
  - Testing Production Build

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