he simplest way to set up a “pushbutton to shut down” is to add “dtoverlay=gpio-shutdown” to /boot/config.txt and rig a NO momentary contact switch across pins 5 and 6. Push once to shut down the system. Push again to reboot it.

dtoverlay=gpio-shutdown,gpio_pin=3

To avoid I2c being unusable:GPIO26 is physical pin 37
dtoverlay=gpio-shutdown,gpio_pin=26

pi@raspberrypi:~ $ dtoverlay -h gpio-shutdown
Name:   gpio-shutdown

Info:   Initiates a shutdown when GPIO pin changes. The given GPIO pin
        is configured as an input key that generates KEY_POWER events.
        This event is handled by systemd-logind by initiating a
        shutdown. Systemd versions older than 225 need an udev rule
        enable listening to the input device:

                ACTION!="REMOVE", SUBSYSTEM=="input", KERNEL=="event*", \
                        SUBSYSTEMS=="platform", DRIVERS=="gpio-keys", \
                        ATTRS{keys}=="116", TAG+="power-switch"

        This overlay only handles shutdown. After shutdown, the system
        can be powered up again by driving GPIO3 low. The default
        configuration uses GPIO3 with a pullup, so if you connect a
        button between GPIO3 and GND (pin 5 and 6 on the 40-pin header),
        you get a shutdown and power-up button.

Usage:  dtoverlay=gpio-shutdown,=

Params: gpio_pin                GPIO pin to trigger on (default 3)

        active_low              When this is 1 (active low), a falling
                                edge generates a key down event and a
                                rising edge generates a key up event.
                                When this is 0 (active high), this is
                                reversed. The default is 1 (active low).

        gpio_pull               Desired pull-up/down state (off, down, up)
                                Default is "up".

                                Note that the default pin (GPIO3) has an
                                external pullup.
The default GPIO is 3 (which appears on pin 5 of the 40-pin header). The pin is configured to pull high by default (which is also the SoC's default), and the GPIO is marked as active low (the opposite to the pull, for obvious reasons).

If you are having trouble, you can debug using raspi-gpio on Raspbian. Assuming for now that the overlay applied correctly (lsmod should show gpio-keys as being loaded), raspi-gpio get 3 will show the pin level (which should be 1) and function (INPUT). Now run it in a loop:

pi@raspberrypi:~ $ while true; do raspi-gpio get 3; done
Attach one end of a patch lead to pin 5 (GPIO3), and touch the other end on pin 6 (GND) - the Pi should shut down immediately, but if not you will see the pin level change to 0.