{"meta":{"title":"Syntax for discussion category forms","intro":"You can use YAML syntax to define the fields in your discussion category forms.","product":"GitHub Discussions","breadcrumbs":[{"href":"/en/discussions","title":"GitHub Discussions"},{"href":"/en/discussions/managing-discussions-for-your-community","title":"Managing discussions"},{"href":"/en/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms","title":"Syntax for discussion category forms"}],"documentType":"article"},"body":"# Syntax for discussion category forms\n\nYou can use YAML syntax to define the fields in your discussion category forms.\n\n## About YAML syntax for discussion category forms\n\nYou 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](https://learnxinyminutes.com/docs/yaml/).\n\nThe 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`.\n\nFor each field, you can define the input type, validation, and a default label.\n\nWhen 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.\n\nThis example YAML configuration file defines a general discussion category form.\n\n```yaml copy\ntitle: \"[General] \"\nlabels: [\"General Introduction\"]\nbody:\n  - type: markdown\n    attributes:\n      value: |\n        This is text that will show up in the template!\n  - type: textarea\n    id: improvements\n    attributes:\n      label: Top 3 improvements\n      description: \"What are the top 3 improvements we could make to this project?\"\n      value: |\n        1.\n        2.\n        3.\n        ...\n      render: bash\n    validations:\n      required: true\n  - type: markdown\n    attributes:\n      value: |\n        ## Markdown header\n        And some more markdown\n  - type: input\n    id: has-id\n    attributes:\n      label: Suggestions\n      description: A description about suggestions to help you\n    validations:\n      required: true\n  - type: dropdown\n    id: download\n    attributes:\n      label: Which area of this project could be most improved?\n      options:\n        - Documentation\n        - Pull request review time\n        - Bug fix time\n        - Release cadence\n    validations:\n      required: true\n  - type: checkboxes\n    attributes:\n      label: Check that box!\n      options:\n        - label: This one!\n          required: true\n        - label: I won't stop you if you check this one, too\n  - type: markdown\n    attributes:\n      value: |\n        ### The thrilling conclusion\n        _to our template_\n```\n\n## Top-level syntax\n\nThe configuration file for a discussion category form must contain a `body` key, and the `body` must contain at least 1 non-Markdown field.\n\n```yaml copy\nbody:\n- type: input\n  id: suggestion\n  attributes:\n    label: Suggestion\n    description: \"How might we make this project better?\"\n    placeholder: \"Adding a CODE_OF_CONDUCT.md file would be a great idea.\"\n  validations:\n    required: true\n```\n\nYou can set the following top-level keys for each discussion category form.\n\n| Key      | Description                                                                        | Required | Type                            |\n| :------- | :--------------------------------------------------------------------------------- | :------- | :------------------------------ |\n| `body`   | Definition of the input types in the discussion form.                              | Required | Array                           |\n| `labels` | Labels that will automatically be added to discussions created with this template. | Optional | Array or comma-delimited string |\n| `title`  | A default title that will be pre-populated in the discussion submission form.      | Optional | String                          |\n\nTo 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](/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema)."}