​Contribute to ​Kestra ​Documentation

Contribute to the Kestra Documentation.

We love documentation contributions. To contribute to the documentation, fork the docs repository and create a pull request with your changes. We'll happily review and merge your suggestions into the documentation set as quickly as we can.

Build the Documentation Locally

The following dependencies are required to build Kestra docs locally:

• Node 14+ and npm
• An IDE (such as VS Code, IntelliJ, etc.)

To start contributing:

• Fork the repository
• Clone the fork on your workstation:

git clone [email protected]:{YOUR_USERNAME}/docs.git
cd docs

Use the following commands to serve the docs locally:

# install dependencies
npm install

# serve with hot reload at localhost:3001
npm run dev

# to generate static pages
npm run generate

# making a production build
npm run build

In addition to contributing content and understanding the overall structure of the documentation, it's important to become familiar with the custom Markdown components and patterns used throughout the Kestra Docs. For those contributing to the Kestra Plugin documentation, a basic understanding of plugin structure and Java syntax for doc strings is required.

This guide is designed to help external contributors get up to speed with the tools, conventions, and components you'll encounter when contributing to Kestra's documentation.

Contribute to the Kestra Documentation

ChildCard

The documentation is structured on multiple levels. The top level is an index page such as "Getting Started," "Workflow Components," and "Cloud & Enterprise Edition." This acts as a landing page for all content that falls under those high-level categories. To serve a visitor everything within that topic, we use a ChildCard component on the index page. This component is built from the ChildCard.vue file in the components/content directory.

The index file's markdown looks like this:

---
title: Getting Started
---

Follow the [Quickstart Guide](./01.quickstart.md) to install Kestra and start building your first workflows.

:::ChildCard
:::

And the page displays the following with all the sub topics of "Getting Started" listed with their card and icon:

Note that when writing a standalone documentation page, the first sentence appears in the ChildCard view to introduce the topic. In the above example for Quickstart Guide this sentence is visible:

Start Kestra in a Docker container and create your first flow.

Ideally, keep this first sentence as clear and concise as possible to not clutter the view on the card.

Front Matter

Each documentation page is expected to include several key front matter properties. We briefly mentioned one of them, icon, in the last section. For example, take our Apps page. This is the front matter specified on the markdown page:

---
title: Apps
icon: /docs/icons/admin.svg
editions: ["EE", "Cloud"]
version: ">= 0.20.0"
docId: apps
---

And this is the resulting view:

Let's discuss each property in more detail.

title

This is simply the title of the page, but it is important to make sure this is clear. Typically, this will be the name of the feature or the concept, but as a contributor, you may want to write your own "How to guide" with your Kestra use case. In this scenario, be clear about the purpose of the guide and with what feature or Plugin (e.g., Access Files on your Local Machine in Kestra ).

icon

Icons are SVG files that are used to identify a certain tool being used or a general concept. They appear at the top of all documentation pages and in the ChildCard of the page. For example, this Neon with Kestra guide has the following properties:

---
title: Connect Neon Database to Kestra
icon: /docs/icons/neon.svg
stage: Intermediate
topics:
  - Integrations
---

And appears on the site as follows:

The icon lives in the public/docs/icons folder path and is specified as Neon, so the correct logo shows for the tool. General icons, such as api.svg or installation.svg, are also available in the folder. If you contribute a guide incorporating a tool without an existing icon, place the appropriate SVG file in this folder and reference it in the front matter.

topics & stage

Our How-To Guides require a couple of extra front-matter properties to provide clarity to the site visitor about the guide's topic and level: topics and stage. Using the same example as above, you can see that the properties are set as stage: Intermediate and topics: Integrations.

---
title: Connect Neon Database to Kestra
icon: /docs/icons/neon.svg
stage: Intermediate
topics:
  - Integrations
---

These properties are const variables set in the GuidesChildCard.vue file of the repository. They have a set list to choose from when classifying a guide. For example, stage can be "Getting Started," "Intermediate," or "Advanced." topics can be a multitude of different concepts such as "Scripting," "Kestra Concepts," "Best Practices," and more. If your guide doesn't fit into any of the existing topics, feel free to suggest a new one, and we’ll review it.

editions

Kestra has three editions: Open Source, Enterprise, and Cloud. A feature or guide may be relevant only to one, two, or all editions, so we have a front-matter property to specify that right at the top of a page for the reader. For example, depending on the Kestra edition, there are different pages relevant to handling secrets. We have a Kubernetes Secrets How-to Guide where we set the edition as OSS in the front matter:

---
title: Set Up Secrets from a Helm Chart
icon: /docs/icons/helm.svg
stage: Getting Started
topics:
  - Kestra Concepts
  - DevOps
editions: ["OSS"]
---

And we have a page for Secrets that is specifically for Enterprise & Cloud users.

---
title: Secrets
icon: /docs/icons/admin.svg
editions: ["EE", "Cloud"]
docId: secrets
---

version

Like editions, some Kestra features are only available in specific Kestra versions and onwards. We use the version property in the front matter to identify this in the documentation. For example, Worker Groups are only available starting in Kestra version 0.10.0. This is specified as follows:

---
title: Worker Group
icon: /docs/icons/admin.svg
editions: ["EE"]
version: ">= 0.10.0"
---

docId

One of Kestra's major benefits is its in-app contextual docs. This means that when constructing flows in the platform, you can access the documentation in the same interface without having to navigate to the browser to check against our documentation. This is done through the docId front matter.

Kestra knows that you are working with Apps, and it can show you the relevant documentation without a task switch.

The same is true for all the main components of Kestra (e.g., Namespace, Flow, Blueprints, Plugins, etc.).

release

release is a front matter property only relevant for our Migration Guides. These guides outline the need-to-know information for upgrading from one version of Kestra to another. This includes renaming a feature or "Before and After" examples of an action in Kestra. Example configuration looks like this:

---
title: Restarting parent flow
icon: /docs/icons/migration-guide.svg
release: 0.21.0
editions: ["OSS", "EE"]
---

Customized text

We use several components to add customized text presentations in the documentation. To differentiate important information from average text, we use three different levels of alert types: "info," "success," and "warning."

Another helpful component we use is ::collapse. This tag keeps the documentation space-efficient and hides long examples or other information that does not need to be seen when scrolling the page. Still, the reader can open it up to reveal its content. This is particularly useful for flows that could otherwise take up a lot of space on a page or FAQ Answers that may not be relevant to every reader and can be selected as needed.

Use the following syntax with whatever should be collapsed within the colons and the title inline with ::collapse:

:::collapse{title="Introduction to whatever is collapsed"}

Here is where the collapsed text goes.

::

Here is a full example using a flow and subflow with a ForEach task: