thanks again @Rup for sparking the path to this answer!
rendering out directly from the required file was at least part of the problem.
i believe the other part was not rendering from inside a function as well as not hooking all of that functionality into an action in the target file.
the problem vanishes and the content renders properly when these steps are followed:
require the file in functions.php using built-in WordPress function to the current theme’s template directory as indicated above.
create a simple action hook in the target file using do_action()
function:
do_action( 'namespace_hook_name' );
create a (pluggable, if necessary) function in required file to render desired content (below is based on GeneratePress formatting). $priority and $accepted_args optional:
if ( ! function_exists( 'namespace_func_name' ) ) {
add_action( 'namespace_hook_name', 'namespace_func_name', $priority, $args );
function namespace_func_name() {
// code to render
}
}
sorry about the code formatting.. still new here <3
search commercial themes for how they use action hooks as well as WordPress’s own default themes to learn more and practice.
https://developer.wordpress.org/reference/functions/do_action/
https://developer.wordpress.org/reference/functions/add_action/