In GitHub, what does a YAML issue form give you that a Markdown issue template does not?

## The two formats GitHub supports two mechanisms for shaping new issues, both stored in `.github/ISSUE_TEMPLATE/` and both read from the repository's **default branch** — a template on a feature branch does nothing until it merges. **Markdown templates** are `.md` files with YAML front matter: - `name` — the label shown on the template chooser - `about` — the one-line description under it - `title` — a pre-filled issue title - `labels`, `assignees` — applied automatically Everything below the front matter is dumped into the issue editor as ordinary Markdown. It is a suggestion. The reporter can select all and delete it, and many do. **Issue forms** are `.yml` files describing a real form. Top-level keys mirror the Markdown ones (`name`, `description`, `title`, `labels`, `assignees`, `projects`), plus `body:` — an ordered list of elements. Each element has a `type` and an `attributes` block, and most accept `validations`. ## The element types - `markdown` — static prose shown to the reporter; it is *not* copied into the resulting issue. Use it for "please search existing issues first". - `input` — a single-line box. Ideal for a version, a URL, an environment name. - `textarea` — a multi-line box. Its `render:` attribute (for example `render: shell`) wraps the answer in a fenced code block automatically, which is how you get readable stack traces without asking people to format them. - `dropdown` — a fixed `options` list; `multiple: true` allows several. This is where you kill free-text chaos in fields like severity or affected component. - `checkboxes` — a list of `options`, each of which can itself be `required: true`. The standard use is a pre-flight acknowledgement ("I searched existing issues"). Each element normally carries an `id`, and `validations: required: true` makes it mandatory. Required fields are the whole point: GitHub refuses to submit the form until they are filled. ## What lands in the issue After submission GitHub converts the answers into a Markdown body: each field's `label` becomes a heading and the answer becomes the text beneath it. So the *stored* issue is still plain Markdown — but it is now predictably shaped, because every issue of that type has the same headings in the same order. That predictability is what makes downstream automation viable: a workflow or a bot can find the version heading with confidence, which is impossible when half the reports are free prose. ## The chooser and config.yml `.github/ISSUE_TEMPLATE/config.yml` controls the template picker itself: - `blank_issues_enabled: false` removes the "open a blank issue" escape hatch, so every issue goes through a form. - `contact_links:` lists external destinations — each with `name`, `url`, and `about` — for traffic that should not become an issue at all: a discussion forum, a security disclosure page, a support desk. That combination is what turns an issue tracker from an inbox into a funnel. ## Tradeoffs Forms are stricter, which is the benefit and the cost. Too many required fields and people abandon the form or type "n/a" everywhere, which is worse than free text because it looks structured and is not. Keep the required set to the fields you would otherwise have to ask for in a comment — version, reproduction steps, expected vs actual — and leave the rest optional. Markdown templates still have a place: for internal repos where the reporter is a colleague who genuinely will fill in the headings, the lower friction is worth it. Forms earn their keep on public repos and on any queue where the reporter and the triager are different people. ## Scope of application Both mechanisms only shape issues opened through the web UI's *New issue* flow. An issue created through the API or by a bot bypasses templates entirely, so validation you truly depend on belongs in an automation that reacts to the opened issue, not only in the form.