About YAML syntax for discussion category forms
You can create custom discussion category forms by adding a YAML form definition file to the /.github/DISCUSSION_TEMPLATE/ folder in your repository. If you're new to YAML and want to learn more, see Learn YAML in Y minutes.
The name must correspond with the slug for one of your discussion categories. For example, the template for the "Announcements" category should be .github/DISCUSSION_TEMPLATE/announcements.yml.
For each field, you can define the input type, validation, and a default label.
When a community member fills out a discussion form, their responses for each input are converted to markdown and added to the body of a discussion. Community members can edit their discussions that were created with a discussion form and other people can interact with the discussion like a discussion created through other methods.
This example YAML configuration file defines a general discussion category form.
title: "[General] " labels: ["General Introduction"] body: - type: markdown attributes: value: | This is text that will show up in the template! - type: textarea id: improvements attributes: label: Top 3 improvements description: "What are the top 3 improvements we could make to this project?" value: | 1. 2. 3. ... render: bash validations: required: true - type: markdown attributes: value: | ## Markdown header And some more markdown - type: input id: has-id attributes: label: Suggestions description: A description about suggestions to help you validations: required: true - type: dropdown id: download attributes: label: Which area of this project could be most improved? options: - Documentation - Pull request review time - Bug fix time - Release cadence validations: required: true - type: checkboxes attributes: label: Check that box! options: - label: This one! required: true - label: I won't stop you if you check this one, too - type: markdown attributes: value: | ### The thrilling conclusion _to our template_
title: "[General] " labels: ["General Introduction"] body: - type: markdown attributes: value: | This is text that will show up in the template! - type: textarea id: improvements attributes: label: Top 3 improvements description: "What are the top 3 improvements we could make to this project?" value: | 1. 2. 3. ... render: bash validations: required: true - type: markdown attributes: value: | ## Markdown header And some more markdown - type: input id: has-id attributes: label: Suggestions description: A description about suggestions to help you validations: required: true - type: dropdown id: download attributes: label: Which area of this project could be most improved? options: - Documentation - Pull request review time - Bug fix time - Release cadence validations: required: true - type: checkboxes attributes: label: Check that box! options: - label: This one! required: true - label: I won't stop you if you check this one, too - type: markdown attributes: value: | ### The thrilling conclusion _to our template_ Top-level syntax
The configuration file for a discussion category form must contain a body key, and the body must contain at least 1 non-Markdown field.
body: - type: input id: suggestion attributes: label: Suggestion description: "How might we make this project better?" placeholder: "Adding a CODE_OF_CONDUCT.md file would be a great idea." validations: required: true
body: - type: input id: suggestion attributes: label: Suggestion description: "How might we make this project better?" placeholder: "Adding a CODE_OF_CONDUCT.md file would be a great idea." validations: required: true You can set the following top-level keys for each discussion category form.
| Key | Description | Required | Type |
|---|---|---|---|
body | Definition of the input types in the discussion form. | Required | Array |
labels | Labels that will automatically be added to discussions created with this template. | Optional | Array or comma-delimited string |
title | A default title that will be pre-populated in the discussion submission form. | Optional | String |
To add fields to your form, include an array of form elements in the body key. For a list of available elements and their syntaxes, see Syntax for GitHub's form schema.