LogoLogo
Bonsai (0.13) DocsGitHubDiscord CommunityGarden Enterprise
Bonsai (0.13)
Bonsai (0.13)
  • Welcome to Garden!
  • 🌸Overview
    • How Garden Works
    • Core Concepts
    • Adopting Garden
    • Garden vs Other Tools
  • 🌳Use Cases
    • Isolated On-Demand Preview Environments
    • Fast, Portable CI Pipelines that Run Anywhere
    • Shift Testing Left
    • Local Development With Remote Clusters
    • Jumpstart your Internal Developer Platform
  • 🌻Getting Started
    • Quickstart Guide
    • Installing Garden
    • Next Steps
  • 💐Tutorials
    • Your First Project
      • 1. Create a Garden Project
      • 2. Pick a Kubernetes Plugin
      • 3. Add Actions
      • 4. Add Tests
      • 5. Code Syncing (Hot Reload)
      • 6. Next Steps
  • 🌿Using Garden
    • About
    • Configuration Overview
    • Projects
    • Dashboard
    • Actions
    • Tests
    • Runs
    • Workflows
    • Variables and templating
    • Config Templates
    • Using the CLI
    • Modules
  • Kubernetes Plugins
    • About
    • Remote K8s Plugin Configuration
      • 1. Create a Cluster
        • AWS
        • GCP
        • Azure
      • 2. Configure Container Registry
        • AWS
        • GCP
        • Azure
        • Docker Hub
      • 3. Set Up Ingress, TLS and DNS
      • 4. Configure the Provider
    • Local K8s Plugin Configuration
      • 1. Install Local Kubernetes
      • 2. Configure the Provider
    • Ephemeral K8s Plugin Configuration
      • 1. Configure the Provider
      • 2. Login to the Garden dashboard
      • 3. Configure Ingress (optional)
      • 4. Retrieve Kubeconfig (optional)
    • Actions
      • Build
        • Container
      • Deploy
        • Kubernetes
        • Helm
        • Container
        • PersistentVolumeClaim
        • ConfigMap
      • Run and Test
        • Kubernetes Pod
        • Helm Pod
        • Kubernetes Exec
        • Container
    • Guides
      • In-Cluster Building
      • Minimal RBAC Configuration for Development Clusters
      • Deploying to Production
      • Using a Registry Mirror
  • ☘️Terraform Plugin
    • About
    • Plugin Configuration
    • Actions
  • 🌹Pulumi Plugin
    • About
    • Plugin Configuration
    • Actions
  • 🌼Other Plugins
    • Container
    • Exec (local scripts)
  • 🌷Guides
    • Migrating to Bonsai
    • Migrating from Docker Compose to Garden
    • Deprecations and updating to Cedar
    • Code Synchronization
    • Connecting a local application to a Kubernetes cluster (Local Mode)
    • Environments and namespaces
    • Using Garden in CircleCI
  • 🪷Advanced
    • Using Remote Sources
    • Custom Commands
  • 🎋Reference
    • Providers
      • conftest-container
      • conftest-kubernetes
      • conftest
      • container
      • ephemeral-kubernetes
      • exec
      • hadolint
      • jib
      • kubernetes
      • local-kubernetes
      • octant
      • otel-collector
      • pulumi
      • terraform
    • Action Types
      • Build
        • container Build
        • exec Build
        • jib-container Build
      • Deploy
        • configmap Deploy
        • container Deploy
        • exec Deploy
        • helm Deploy
        • kubernetes Deploy
        • persistentvolumeclaim Deploy
        • pulumi Deploy
        • terraform Deploy
      • Run
        • container Run
        • exec Run
        • helm-pod Run
        • kubernetes-exec Run
        • kubernetes-pod Run
      • Test
        • conftest-helm Test
        • conftest Test
        • container Test
        • exec Test
        • hadolint Test
        • helm-pod Test
        • kubernetes-exec Test
        • kubernetes-pod Test
    • Template Strings
      • Project template context
      • Environment template context
      • Provider template context
      • Action (all fields) template context
      • Action spec template context
      • Module template context
      • Remote Source template context
      • Project Output template context
      • Custom Command template context
      • Workflow template context
      • Template Helper Functions
    • Commands
    • Project Configuration
    • ConfigTemplate Reference
    • RenderTemplate Reference
    • Workflow Configuration
    • Garden Containers on Docker Hub
    • Module Template Configuration
    • Module Types
      • configmap
      • conftest
      • container
      • exec
      • hadolint
      • helm
      • jib-container
      • kubernetes
      • persistentvolumeclaim
      • pulumi
      • templated
      • terraform
  • 🌸Misc
    • FAQ
    • Troubleshooting
    • Telemetry
    • New Garden Cloud Version
  • Contributing to Garden
    • Contributor Covenant Code of Conduct
    • Contributing to the Docs
    • Setting up your developer environment
    • Developing Garden
    • Config resolution
    • Graph execution
Powered by GitBook
On this page
  • How our docs are structured
  • Making your first contribution
  • Moving or renaming files
  • Syntax

Was this helpful?

  1. Contributing to Garden

Contributing to the Docs

PreviousContributor Covenant Code of ConductNextSetting up your developer environment

Last updated 2 months ago

Was this helpful?

How our docs are structured

Our docs are centralized inside the docs/ folder of our GitHub repository for garden. These files are synced to GitBook, our documentation publishing tool, which composes them into what users see when they navigate to .

We have an additional class of documentation, which lives as README.md files inside each of our examples inside examples/. These files are not synced to GitBook and are intended to be discovered by our more technical users.

Our ../../gitbook.yaml file determines link redirects and the basic structure of our documentation “tree”. You can find more documentation on this file .

*The README.md file at the top of the docs/ folder and the reference/* files are all auto-generated and should never be touched directly. Refer to for details.

Making your first contribution

There's a few things you'll need to make your first contribution to the docs:

  1. A local copy of the garden Git repository downloaded to your machine. You can find instructions in GitHub's official documentation for .

  2. Garden's developer tools installed. Our

  3. Some basic knowledge of Git. If one or more users are contributing to the docs at the same time you are, it is likely you will need to resolve merge conflicts on the CLI or in your visual Git tool. GitHub has or you can use a simple, visual Git tool like available for macOS and Windows. a. In case of emergencies, refer to . b. For new learners, the can teach you Git.

  4. Some form of Markdown linter. A linter enforces standards and consistency in your Markdown writing. The industry standard is . A .

Make your changes and open a pull request (PR)

Create a branch to hold your work, change any files you wish to change, save them, then commit them to your branch. Try and keep your branches focused around a specific theme. Your commits will need to be prepended with a keyword that follows the Conventional Commits specification, e.g. docs: added docs contributor page. See our documentation for .

Before pushing your changes, run npm run build to refresh the Table of Contents contained at ../docs/README.md with any additions or changes you've made.

If you've moved or renamed files, refer to .

Now push your changes to our remote Git repository hosted on GitHub, then and request a review from and/or . View our for more.

Moving or renaming files

When moving or renaming files, special care must be taken to ensure any existing internal and external links continue to work.

First, use git mv when moving files. git mv is a convenience function that ensures Git can track the renaming as a file rename rather than a file deletion and a new file creation.

We also need to change any existing redirects inside ../gitbook.yaml to point to our new location:

For every file you've renamed or moved, make sure to add a new redirect in ../gitbook.yaml pointing from its old location to its new location unless you're sure no one externally has linked to it.

Do not change absolute URLs within the same pull request. Absolute URLs are links beginning with https:.

Finally, run npm run build to regenerate the Table of Contents.

Absolute URLs vs relative URLs and when to use them

Use absolute URLs when you need to point to any docs from outside the docs/ folder. This is often the case when you're working in TypeScript (.ts) files. Here's an example from our ../../core/src/graph/actions.ts file that includes a URL intended for users of garden:

    if (config.include && config.include.length !== 0) {
      throw new ConfigurationError({
        message: deline`Action ${config.kind}.${config.name} (defined at ${configPath})
        tries to include files but excludes all files via "**/*".
        Read about including and excluding files and directories here:
        https://docs.garden.io/using-garden/configuration-overview#including-excluding-files-and-directories`,
      })
    }

This URL would need to be changed or a redirect link set if the configuration-overview file were to move.

Creating a new section

To create a new section, create a folder and add a README.md file with the contents title and order e.g.

---
order: 2
title: Tutorials
---

Syntax

Our docs are written in the CommonMark specification of Markdown with additional “blocks” provided by GitBook, our documentation publisher.

You'll notice YAML “front-matter” at the top of each docs page: this tells GitBook how to present our page visually and order it in any given section.

The YAML front-matter looks like this:

---
title: Contributing to the Docs
order: 3
---

Markdown normally expects the first heading of any page to be a top-level, usually the title of the page, e.g. # Contributing to the Docs. However, when we specify the title of the page in the front-matter, start the page without the top-level and begin at the second-level heading, ##, as GitBook will automatically pull in the title for you.

Second, update any internal and external links to point to your moved or renamed file, then update ../gitbook.yaml to redirect visitors to your new location. To illustrate this, here's a visual example of moving our to a new Getting Started section.

Quickstart link changed to point to new relative URL
Redirect links pointing to new locations

The second line, quick-start: getting-started/quickstart.md means any users visiting will automatically redirect to .

You'll also need to find and replace all instances of links within the garden repository to your file. An editor like Visual Studio Code will have a .

Instead, change all the relative URLs inside docs/, , then make a new PR to update these absolute URLs. This is to avoid broken links.

The order should correspond to its position from top to bottom in the sidebar on and the title should be the title of the section as it appears in the sidebar. We like to use a floral-themed emoji to demarcate new sections .

We use the and blocks from GitBook.

GitBook supports a of headings.

Quickstart guide
https://docs.garden.io/quick-start
https://docs.garden.io/getting-started/quickstart
find and replace feature
submit your PR
🌹
https://docs.garden.io
Hint
Tabs
maximum of three levels
https://docs.garden.io
at GitBook's website
cloning a Git repository
documentation on resolving merge conflicts using the CLI
Fork
Oh Shit, Git!?!
computer game, Oh my Git!
markdownlint
markdownlint extension is available for Visual Studio Code
a list of Conventional Commit keywords
open a pull request
Eysi
worldofgeese
contributing guidelines
Make your changes and open a pull request (PR)
Moving or renaming files
documentation explains how to install Garden's developer tools