Documentation for Dummies (like me)

I’m messing around with ACF Blocks as part of some training materials I’m preparing. To me, ACF Blocks really are the missing transition piece from “classic WordPress” to “modern WordPress” because they make the process of inserting custom HTML/PHP into the block editor much easier- and much faster- than native Gutenberg blocks.

The last time I used ACF Blocks was before they supported using block.json as a way to register your block. In the past, I had used acf_register_block_type(), which takes an array in PHP, similar to the old ACF Options pages. Well, now you can use WordPress’s native register_block_type(), which takes a JSON file. That’s great! Anything that brings us closer to native WordPress methods is good practice.

Aside: To be honest, I do have experience with building native blocks, but the point of this training is to be in the mindset of someone who hasn’t done anything in Gutenberg, someone who only has experience using ACF to build their WordPress sites.

Step one, I set about making an acf-blocks/ folder in my theme:

├── acf-blocks

So my templates directory full of flexible content template parts looks like this:

├── templates
│   ├── row-featured_posts.php
│   ├── row-hero.phpCode language: CSS (css)

but it will become this:

├── acf-blocks
│   ├── featured_posts.php
│   ├── hero.phpCode language: CSS (css)

Great. There’s really not much to do in the actual PHP files to make them ACF Block ready. I need to update get_sub_field() functions to get_field() but otherwise, ACF Blocks really do function a lot like Flexible Content rows. (Of course there’s other fancy stuff we can play with, like the $block variable, but we’re not there yet.)

Well, it was pretty late at night, so my brain wasn’t running at optimal speed. I started making the JSON files for my new ACF Blocks so I could register them:

├── acf-blocks
│   ├── featured_posts.php
│   ├── featured_posts.json
│   ├── hero.php
│   ├── hero.jsonCode language: CSS (css)

Can you spot the mistake? It’s pretty dumb and obvious, if I’m being honest. I caught it fairly quickly, but not nearly as quickly as if it were 9 am and I was fully coffee’d up.

When you register a block with a block.json file, you have to actually name the file block.json. It sounds pretty silly when I say it out loud, but of course that’s the case. But here’s the thing about documentation. It never really says that. I mean, it keeps saying block.json file, but.. yeah.. I messed up.

One of Advanced Custom Fields’ strongest features is its robust documentation. They have code examples for everything. They have pages for each field type, each hook, each function. They have guides and how-tos, but mostly they have clear examples. The documentation is great.

When dealing with ACF Blocks however, the documentation seems to struggle from the same issues as the Gutenberg project: there’s so many moving parts, they’ve sort of abandoned traditional documentation and relied more on release notes and links to blog posts. Their main resource for the use of block.json doesn’t include full examples and instead sends you to a release notes blog post. And there’s about five disparate posts you’ll need to find and dig through to get a good handle on using ACF Blocks.

My main complaint here is that the language sounds like they’re writing it from the perspective of users coming from native blocks or at least some awareness of what’s happening the block editor:

Since WordPress 5.8, WordPress has supported – and recommended – that blocks are registered through a JSON configuration file. All of the WordPress Block Documentation was migrated to only show block.json configuration objects, and it became confusing for users to know what WordPress configuration options were usable in ACF PRO. ACF 6.0 introduces support for block.json registration of blocks with ACF.


This is important stuff and a great explanation, but I also wonder how many of their users are wanting to move into ACF Blocks without intimate knowledge of the block editor and how block.json files work. Where your user is coming from is extremely important, and documentation should take that into consideration. I think this is just one of the side effects of the current “transition period” in WordPress: documentation needs to appeal to the experienced JavaScript developer but also the traditional PHP developer. It’s hard and it’ll take some time.

Here’s where the folder structure ended up for me:

├── acf-blocks
│   ├── featured_posts
│   |   ├── block.json
│   |   ├── render.php
│   ├── hero
│   |   ├── block.json
│   |   ├── render.php

It has its pros and cons. It’s not as easy to read, maybe a bit more cluttered. I love breaking things into files and folders, but the fact that the files all have the same name gets a little annoying when you have multiple tabs open. But it brings me closer to the “native block” approach (dynamic blocks often include a render.php file). Which is where I’m going anyway.

Overall I’m hopeful that documentation in WordPress will catch up. And not just official documentation, but the community documentation- the best practices and how-tos that I relied on when I first started building WordPress websites. I know many of us are Not Sure How to WordPress Anymore but I’m feeling more optimistic every day.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.