Drupal7: render arrays

There is a lot of overlap between information here and the Drupal7 theming zone and the Drupal7 Forms, the Form API (FAPI), and Forms tutorials section.
GOTCHA: from How to nest elements in a render array :

If an element is given #markup, the render process stops searching for nested elements. 2011, tim.plunkett

GOTCHA: from The magic behind Drupal’s render elements (2013, Andrew Marcus):

While some value keys are standard for all render arrays or forms, most are actually dependent on the theme that ultimately renders each element. These keys can be found in drupal_render(), form_builder(), and element_children().

Any key that is not listed in one of these functions is instead used by the theme functions. The theme functions that make up forms try to do a good job of standardizing keys and reusing them across themes; these are documented here. However, this reference does not include non-form render array types, which may or may not use these same keys. For instance, in the example above, the 'container' type expects the '#attributes' key, but the 'markup' type does not, so passing an '#attributes' key to that element won’t do anything. Similarly, the '#title' and '#href' keys would be meaningless in the 'container' element.

Visit also