Inserting a Template File in WordPress the Right Way

The WordPress template hierarchy

If you’re coming from a static HTML background, WordPress can feel confusing at first. You create an about-us.html file, upload it to your server, and expect it to work like a normal webpage. But when you try to access it, something feels off. The styling is missing, WordPress features don’t work, and you realize you’re outside the system entirely.

Here’s the fundamental shift you need to make: WordPress doesn’t serve static files from your disk. Every post, page, and piece of content lives in the database. The template files you create are blueprints, not standalone pages. WordPress loads its engine, grabs the content from the database, and pours it into those templates before sending the result to the browser.

This architecture is powerful, but it requires a different mental model. Let’s walk through how to properly add custom templates, include them in your theme, and link to them without breaking everything.

The Wrong Way: Direct PHP Files

Consider this scenario. You create a file called about-us.php in your theme folder and upload it. You then try to visit yoursite.com/wp-content/themes/yourtheme/about-us.php.

What happens? The file loads, but it has no access to WordPress functions. get_header() fails. Your menu doesn’t appear. Your styling is missing. The user session and login status are invisible. You are essentially standing outside the house looking through the window.

Why this fails: When you access a PHP file directly, the WordPress core never loads. No database connection, no query, no template hierarchy. You get a blank, lonely file with no context.

The Right Way: Page Templates

The correct approach is to create a page template that WordPress recognizes and can use to display content from the database.

Step 1: Create Your Template File

In your theme folder, create a file called about-us.php. At the very top, add this comment block:

php

<?php
/**
 * Template Name: About Us
 */

get_header();
?>

<div class="content-area">
    <h1><?php the_title(); ?></h1>
    <div class="entry-content">
        <?php the_content(); ?>
    </div>
</div>

<?php get_footer(); ?>

This single comment—Template Name: About Us—tells WordPress this file exists and can be selected as a template.

Step 2: Create the Page in Admin

  1. Go to Pages > Add New.
  2. Give it a title: “About Us.”
  3. In the Page Attributes meta box on the right, find the Template dropdown.
  4. Select “About Us” (the name you defined in the comment).
  5. Add your content in the editor. This content will be pulled from the database and displayed wherever the_content() appears in your template.
  6. Click Publish.

Now when you view this page, WordPress loads its engine, queries the database for the page content, and uses about-us.php as the blueprint. The URL will be something like yoursite.com/about-us (depending on your permalink settings). Clean, secure, and fully integrated.

The Right Way: Reusable Template Parts

Sometimes you don’t want a full page template. You just want to include a reusable piece of code across multiple templates—a custom section, a complex loop, a specialized call-to-action block.

WordPress provides the get_template_part() function for exactly this purpose.

Step 1: Create the Template Part

Inside your theme folder, create a subfolder called template-parts (this is a convention, not a requirement). Inside it, create a file called content-featured.php:

php

<?php
// template-parts/content-featured.php
?>
<div class="featured-section">
    <h2>Featured Resources</h2>
    <?php
    $featured_posts = new WP_Query(array(
        'posts_per_page' => 3,
        'meta_key' => 'featured',
        'meta_value' => 'yes'
    ));
    
    if ($featured_posts->have_posts()) :
        while ($featured_posts->have_posts()) : $featured_posts->the_post();
            ?>
            <article>
                <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                <?php the_excerpt(); ?>
            </article>
        <?php endwhile;
        wp_reset_postdata();
    endif;
    ?>
</div>

Step 2: Include It in Your Templates

Now, anywhere you want this featured section to appear, you call get_template_part():

php

<?php get_template_part('template-parts/content', 'featured'); ?>

WordPress will look for template-parts/content-featured.php and include it. The function is smart—it allows for fallbacks and keeps your templates clean and modular.

Why This Matters: Instead of copying and pasting the same 20 lines of HTML and PHP across multiple template files, you define it once and reuse it. When you need to update the design, you change one file. This is the professional way to build WordPress themes.

Linking to Your Pages: The Correct Method

The Stack Overflow answer mentioned linking to a PHP file directly. Let’s be clear: you should never hardcode a link to a PHP file in your theme. Those paths break when you change permalinks, move servers, or update your theme.

Instead, use WordPress functions that generate URLs dynamically.

For Pages You Created:

php

<a href="<?php echo get_permalink(get_page_by_path('about-us')->ID); ?>">
    About Us
</a>

This looks up the page by its slug (about-us) and returns its permalink. Even if you change the URL structure later, this link continues to work.

For the Homepage:

php

<a href="<?php echo home_url(); ?>">Home</a>

For a Specific Page Using Its Slug:

php

<a href="<?php echo site_url('/about-us/'); ?>">About Us</a>

The site_url() function returns your site’s base URL, and you append the path. This is simpler than the get_permalink() approach but slightly less dynamic. Both work.

A Complete Example: Building an About Page the Right Way

Let’s walk through a full, production-ready example.

Step 1: Create about-us.php in your theme folder with the template header.

Step 2: Add your custom markup, loops, and WordPress functions:

php

<?php
/**
 * Template Name: About Us
 */

get_header();
?>

<main id="primary" class="site-main">
    <div class="container">
        <header class="page-header">
            <h1 class="page-title"><?php the_title(); ?></h1>
        </header>

        <div class="page-content">
            <?php the_content(); ?>
            
            <?php get_template_part('template-parts/team', 'members'); ?>
            
            <?php get_template_part('template-parts/contact', 'cta'); ?>
        </div>
    </div>
</main>

<?php get_footer(); ?>

Step 3: Create your template parts.

template-parts/team-members.php:

php

<div class="team-section">
    <h2>Meet Our Team</h2>
    <div class="team-grid">
        <?php
        $team_members = new WP_Query(array(
            'post_type' => 'team',
            'posts_per_page' => -1,
            'orderby' => 'menu_order'
        ));
        
        if ($team_members->have_posts()) :
            while ($team_members->have_posts()) : $team_members->the_post();
                ?>
                <div class="team-card">
                    <?php if (has_post_thumbnail()) : ?>
                        <div class="team-photo">
                            <?php the_post_thumbnail('medium'); ?>
                        </div>
                    <?php endif; ?>
                    <h3><?php the_title(); ?></h3>
                    <p class="team-position"><?php echo get_post_meta(get_the_ID(), 'position', true); ?></p>
                    <?php the_excerpt(); ?>
                </div>
            <?php endwhile;
            wp_reset_postdata();
        endif;
        ?>
    </div>
</div>

Step 4: Create the page in WordPress admin, assign the “About Us” template, and publish.

Now your about page has a custom design, pulls content from the database, includes reusable components, and integrates fully with WordPress. All without a single direct link to a PHP file.

Common Pitfalls to Avoid

  • Direct PHP Access: Never link directly to wp-content/themes/yourtheme/file.php. It bypasses WordPress entirely.
  • Hardcoded Paths: Avoid href="http://yoursite.com/about-us". Use echo site_url('/about-us/'); instead.
  • Missing Template Header: Without Template Name: About Us in the file, it won’t appear in the admin dropdown.
  • Forgotten the_content(): If your template doesn’t include the_content(), the page content you wrote in the editor will never display.
  • Confusing get_template_part(): The function expects a slug, not a full path. get_template_part('content', 'featured') looks for content-featured.php, not content/featured.php.

The Takeaway

WordPress is a system, not a collection of static files. Once you embrace that, everything becomes simpler. Create page templates with proper headers. Use get_template_part() for reusable components. Generate URLs dynamically with WordPress functions. Your code becomes cleaner, your sites become more maintainable, and you stop fighting the platform.

The old static HTML mindset served you well. But to build truly powerful WordPress sites, you need to work with the architecture, not around it. Start with one template, build it correctly, and watch how the rest falls into place.

Was this post helpful?
Buy us a coffee!
Tags: