Create a custom post type in WordPress: code or ACF
Create a custom post type by calling register_post_type() on WordPress's init hook, or use ACF's Post Types screen to register it through the dashboard. For code, keep the registration in a site plugin so it does not disappear when you change themes. Choose one registration method for each post-type key.
This guide creates public Books content with Genres for grouping. You will also see how the internal key, dashboard label and public URL slug differ.
1. Decide between code and ACF
With code, you keep the definition in a file you can review and version. With ACF, you manage that configuration through the dashboard. Neither route automatically designs a book page or makes public content private.
ACF introduced its post-type and taxonomy registration interface in version 6.1, in both its free and Pro editions. That availability is documented in the ACF 6.1 release announcement and was checked in November 2026. Custom fields are a separate feature: you do not need to add fields just to create a post type.
Use local WordPress or staging first. Keep a backup and file access for recovery. Do not run both the PHP example and an ACF definition with the same key at once. If you are changing registration providers, preserve the existing key and test that transition on a copy of the site.
This example is public. Do not reuse it for confidential client records without designing the capabilities, access controls and REST behavior for that purpose.
2. Add the code as a normal plugin
Create wp-content/plugins/wpgeared-books/wpgeared-books.php and paste the complete file below. Use a normal plugin, not an mu-plugins file, because this example relies on activation and deactivation hooks.
<?php
/**
* Plugin Name: WPGeared Books
* Description: A public Books post type with a Genres taxonomy.
* Version: 1.0.0
*/
defined( 'ABSPATH' ) || exit;
function wpgeared_register_books() {
register_post_type(
'wpgeared_book',
array(
'labels' => array(
'name' => 'Books',
'singular_name' => 'Book',
'add_new_item' => 'Add New Book',
'edit_item' => 'Edit Book',
),
'public' => true,
'show_in_rest' => true,
'has_archive' => true,
'rewrite' => array( 'slug' => 'books', 'with_front' => false ),
'supports' => array( 'title', 'editor', 'excerpt', 'thumbnail' ),
'taxonomies' => array( 'wpgeared_genre' ),
'menu_icon' => 'dashicons-book',
)
);
register_taxonomy(
'wpgeared_genre',
array( 'wpgeared_book' ),
array(
'labels' => array( 'name' => 'Genres', 'singular_name' => 'Genre' ),
'public' => true,
'hierarchical' => true,
'show_in_rest' => true,
'rewrite' => array( 'slug' => 'book-genre', 'with_front' => false ),
)
);
}
add_action( 'init', 'wpgeared_register_books' );
function wpgeared_books_activate() {
wpgeared_register_books();
flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'wpgeared_books_activate' );
function wpgeared_books_deactivate() {
unregister_taxonomy( 'wpgeared_genre' );
unregister_post_type( 'wpgeared_book' );
flush_rewrite_rules();
}
register_deactivation_hook( __FILE__, 'wpgeared_books_deactivate' );
Activate WPGeared Books under Plugins. You should see Books in the dashboard menu.
Understand the three names
| Purpose | This example | Where it matters |
|---|---|---|
| Internal post-type key | wpgeared_book |
Database records, APIs and template filenames |
| Dashboard label | Books | Menus and editor labels |
| Public rewrite slug | books |
Pretty URLs such as /books/example-title/ |
The key must fit WordPress's registration rules, including its 20-character limit. Avoid changing it after adding content just because you want a different menu label. The register_post_type reference explains the key and supported arguments.
Why these settings are present
public makes this a public content type. show_in_rest enables its REST integration, which the block editor needs. The editor support is also included, alongside title, excerpt and thumbnail support. A featured-image control still depends on the active theme supporting post thumbnails.
has_archive enables a listing for the type. rewrite controls the pretty permalink base. with_front is false so a front prefix from the site's permalink structure is not prepended to this custom base. These settings do not create a menu link automatically. Add the archive link to navigation if visitors need it.
The plugin registers on init, rather than running registration at an arbitrary point while WordPress is loading. That lets WordPress register the content types at the expected point in the request.
3. Add a taxonomy for grouping
The same function registers wpgeared_genre for Books. Its hierarchical setting lets editors create parent and child genres, similar to category organization. A nonhierarchical taxonomy would behave more like tags.
The taxonomy has its own key and URL base, book-genre. It is explicitly connected to wpgeared_book, and it is enabled for REST use so the block editor can work with it. The register_taxonomy reference describes these controls.
A taxonomy is not a new post type. “Book” describes the content record. “History” or “Fiction” can be genre terms applied to those records. Keeping that distinction clear avoids creating separate post types for every category of the same material.
4. Refresh rewrite rules once, not on every visit
On activation, the plugin registers the type and taxonomy before calling flush_rewrite_rules(). WordPress can then rebuild routing with those definitions available.
Do not move the flush into the normal init callback. Rebuilding rewrite rules is unnecessary work on ordinary requests. The flush_rewrite_rules reference warns about its cost, while the plugin lifecycle documentation explains activation hooks.
If you edit the rewrite slug while the plugin is already active, its activation hook does not run just because the file changed. On staging, save Settings → Permalinks once, or deliberately deactivate and reactivate the sample plugin. Then recheck the URLs.
For the pretty URL examples, choose a pretty permalink structure on the test site. With plain permalinks, use the links WordPress generates rather than expecting /books/ to behave identically. Also check for an existing Page or another registration already using books.
5. Use ACF instead of the PHP registration
Skip this section if you are keeping the code route. These are documentation-based steps for ACF's interface, not a claim that every version has identical screen labels.
- Disable the sample code registration on staging before creating the equivalent ACF definition.
- Open ACF → Post Types and add a post type.
- Set the plural label to Books, singular label to Book, and post-type key to
wpgeared_book. - Enable the public settings you need. Enable REST API access and editor support. Add title, excerpt and thumbnail support to match the PHP example.
- In the advanced URL settings, enable an archive and use
booksas the rewrite slug. Match the front-prefix behavior if you need equivalent URLs. - Save the definition. Add a taxonomy under ACF's Taxonomies screen, with key
wpgeared_genre, and connect it to Books. Enable hierarchy and REST support. Set its rewrite slug tobook-genreand disable the front URL prefix to match the PHP taxonomy. - Refresh permalinks once if needed, then run the same checks as the code route.
The ACF custom post-type guide is the reference for the interface. Check explicit settings rather than relying on a screenshot's defaults.
Use Advanced Custom Fields when following these steps, not a similarly named fork. If you later attach fields such as an ISBN, add a field group with a location rule for Books. ACF's post-type and taxonomy overview explains that relationship.
6. Choose the right templates
Registration makes the content type and its routes available. Your theme still decides how the pages look.
For a classic theme, the specific filenames are:
single-wpgeared_book.php
archive-wpgeared_book.php
Place customizations in a child theme rather than editing a parent theme that an update can replace. For a block theme, use templates/single-wpgeared_book.html and templates/archive-wpgeared_book.html. A saved Site Editor template can take precedence over a theme file, so check for an existing customization if your file does not change the layout.
Notice that the filenames use wpgeared_book, the internal key. They do not use the books rewrite slug. You can begin without specific templates and inspect the theme's fallback layout before adding a custom design. The WordPress template hierarchy describes the fallback order.
7. Check content, URLs and public access
Create a test Book with a title, body and genre, then publish it. Check:
- The single link generated by WordPress loads the intended book.
- The Books archive lists published books.
- A genre archive groups the correct books.
- The block editor opens and the expected controls are available.
- A second Book left as a draft is not publicly listed.
With the code example's default REST base, inspect /wp-json/wp/v2/wpgeared_book while logged out. Published records should be accessible, while drafts should not appear in that anonymous collection. Do not use an administrator's authenticated session as your only privacy check. For a separate custom API route, see the REST endpoint guide.
Troubleshoot and undo
Archive returns 404: check the archive setting, pretty permalinks, slug collisions and a one-time rewrite refresh. Do not add a permanent flush on every request.
No block editor: confirm both REST exposure and editor support, then check whether another plugin deliberately disables the editor for this type.
No featured image: check post-type support and theme thumbnail support. Adding the type alone cannot supply missing theme support.
The page has the wrong layout: inspect the internal-key template name and theme fallback. A registration plugin does not replace theme design.
To undo the sample, deactivate its plugin. It unregisters the type and taxonomy and refreshes routing without deleting their content records. The menu and custom routes disappear, but reactivating the same registration makes those records available again. Keep a backup before changing registration methods, and do not confuse hiding a type with erasing its data.
If the next requirement is an editor component rather than another content type, the ACF Blocks tutorial covers that separate problem.