service/donate.md

@@ -575,35 +575,50 @@ As of 1/16/25, perk data exported from CiviCRM needs to be massaged into valid
 JSON data before it can be used to update the `perks.json` datafile which `donate-neo`
 pulls from. For reference, here are the changes which must be made to the export file
 before it can be used to update the `donate-neo` repo:
+
 1. The data object exported from CiviCRM is a square-braces array, and is not named;
    to conform to JSON standards it must be wrapped in an object's curly braces and
    must be named "perks". Other extraneous text prepending the array must be removed.
+
    a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}`
+
 2. Product `id` fields must be expressed as strings, but are exported from CiviCRM as 
    integers. (See [tpo/web/donate-neo/commit/b23e7fdd](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/b23e7fdd59a66658f50ede630ed924b0006a6439).) Wrap all such IDs in quotes.
+   
    a. For example, `"id": 1` must become `"id": "1"`.
-3. Each "perks" array item contains a child item `product_id.options`. If the perk
-does not have options (such as the sticker pack), CiviCRM will export this field as
-`null`. However, CiviCRM expects `donate-neo` to pass an option SKU along with a perk's
-ID when selected - keeping this field `null` will keep selected perks from being
-recorded in the CRM. (See [tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add
-a mock option SKU in place of `null` in such cases.
+
+3. Each "perks" array item contains a child item
+   `product_id.options`. If the perk does not have options (such as
+   the sticker pack), CiviCRM will export this field as
+   `null`. However, CiviCRM expects `donate-neo` to pass an option SKU
+   along with a perk's ID when selected - keeping this field `null`
+   will keep selected perks from being recorded in the CRM. (See
+   [tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add a mock
+   option SKU in place of `null` in such cases.
+
    a. For example, `"product_id.options": null` must become
    `"product_id.options": ["STI-CKR-00=Sticker"]` (or something similar).
+
 4. Ensure all prices are expressed in number of cents (`2500`) rather than number of dollars (`25`).
-5. CiviCRM is able to store and serve image files related to perks, but we should serve these
-images from `donate-neo` along with the rest of the site assets. As well, CiviCRM does not
-properly store .pngs with transparency layers, rendering them instead as matte black.
-In order to render and serve these images as intended, we store them as base64-encoded
-strings in the JSON itself, under the key `"product_id.imageForDonateNeo"`. 
+
+5. CiviCRM is able to store and serve image files related to perks,
+   but we should serve these images from `donate-neo` along with the
+   rest of the site assets. As well, CiviCRM does not properly store
+   .pngs with transparency layers, rendering them instead as matte
+   black.  In order to render and serve these images as intended, we
+   store them as base64-encoded strings in the JSON itself, under the
+   key `"product_id.imageForDonateNeo"`.
+   
    a. Ensure your string is encoded as a data URI, e.g. beginning with `data:image/png;base64,`.
-6. `product_id.optionsForDonateNeo` is used by `donate-neo` to build out the form UI
-used by the donor to select perk options. It was designed to serve an option-selection
-UI similar to `donate-paleo`'s, in which a given perk might have two options, the
-second dependent on the first.
-For example, a T-shirt perk might come in different cuts, like "Classic" and "Slim
-Fit", but each cut would have separate sizes to pick from.
-Please ensure that `product_id.optionsForDonateNeo` contains data formatted like so:
+
+6. `product_id.optionsForDonateNeo` is used by `donate-neo` to build
+   out the form UI used by the donor to select perk options. It was
+   designed to serve an option-selection UI similar to
+   `donate-paleo`'s, in which a given perk might have two options, the
+   second dependent on the first.  For example, a T-shirt perk might
+   come in different cuts, like "Classic" and "Slim Fit", but each cut
+   would have separate sizes to pick from.  Please ensure that
+   `product_id.optionsForDonateNeo` contains data formatted like so:
 
    ```
    "product_id.optionsForDonateNeo": {
@@ -630,6 +645,7 @@ Please ensure that `product_id.optionsForDonateNeo` contains data formatted like
      }
    },
    ```
+
    `donate-neo` will refrain from visually rendering single-selection option groups, but these must be
    included so they can be embedded as (hidden) form elements, which are then passed along to
    CiviCRM.