GitHub Classic Markdown Issue Template

Classic Markdown Issue Template

Before GitHub introduced YAML issue forms in 2021, Markdown templates were the only option. They remain useful for simple templates, GitLab compatibility, and repositories that prefer editable issue bodies.

Front Matter

---
name: Bug Report
about: Create a report to help us improve
title: "[Bug]: "
labels: bug, triage
assignees: octocat, maintainer2
---

## Describe the Bug

A clear and concise description of what the bug is.

## Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior

A clear and concise description of what you expected to happen.

## Screenshots

If applicable, add screenshots to help explain your problem.

## Environment

- OS: [e.g. macOS 14]
- Browser: [e.g. Chrome 120]
- Version: [e.g. 2.3.1]

## Additional Context

Add any other context about the problem here.

YAML Front Matter Fields

Field	Purpose	Required
name	Template name in the chooser	Yes
about	Description shown in the chooser	Yes
title	Pre-filled issue title	No
labels	Comma-separated labels to auto-apply	No
assignees	Comma-separated GitHub usernames	No

When to Use Markdown over YAML Forms

• Simple templates: When you only need text sections with guidance
• Cross-platform: When the same template must work on both GitHub and GitLab
• Editable structure: When you want reporters to have full control over the final issue format
• Legacy support: For GitHub Enterprise instances that may not support YAML forms

Markdown vs. YAML Forms Comparison

Markdown templates give reporters complete freedom to edit the issue body, which can be both an advantage (flexibility) and a disadvantage (inconsistent submissions). YAML forms enforce structure but are GitHub-only.