I have a page “Portfolio”, it contains a loop that outputs the list of portfolio (Custom Post Type, is this the problem?) items using
page-portfolio.php. Problem is somehow WordPress used the
archive.php to render my portfolio page, why is that?
An archive of a custom post type is displayed using
archive.php if the first does not exist (see the Template Hierarchy for the full details).
page-[posttype].php is only used if you create a “dummy” page to show a custom post type archive (before WordPress 3.1).
So in your case you should rename
archive-portfolio.php, and don’t include a header to indicate a page template name.
I don’t think it is possible to use portfolio.php for the Custom Post Type “Portfolio”.
The way I have solved it on a site I did recently was to call my Custom Post Type “Project” instead. Then pull the content in via a Page Template called portfolio.php (see Brady’s answer).
Then to show the single Projects, I use a template called single-project.php
Make sure you have added the comment block to your
page-portfolio.php to tell its a template.
Add this to the top of the file:
<?php /* Template Name: A Template Name of Your Choice */ ?>
Go into pages in the admin area of WordPress and create a page and assign the above template to that page.