The shape of it. Building your first PageMotor plugin. One folder, one PHP file. You declare a class, opt into the capabilities you need, activate it, and PageMotor does the rest. This takes you from an empty folder to a working shortcode.
Opt in, don’t hook in. The whole mental model first, because once you have it the rest is mechanical. A plugin is a folder under user-content/plugins, with a plugin.php inside it. That file declares a PHP class extending PM_Plugin. And you add capabilities by implementing valet methods: named methods that PageMotor calls at specific moments. Implement shortcodes, and you have shortcodes. Implement nothing at all, and you have a perfectly valid plugin that simply does nothing. You opt in, rather than hooking in.
The folder and the header. Step one, the folder and the header. Make your folder under user-content/plugins, and create plugin.php inside it. Name the folder in kebab case, and start it with a prefix unique to you or your organisation, so it cannot collide with anything else in the ecosystem. Then open that file and add the header comment. PageMotor reads that comment to identify the plugin, so it must sit at the very top of the file, before any PHP code at all.
Only the first 2 KB are read. Here is the first thing that catches people. PageMotor reads only the opening two kilobytes of plugin.php when it looks for the headers. Push a header below a long description or licence block, and PageMotor simply never sees it. Nothing errors, nothing warns you, the field is just quietly blank. So keep the header comment short, and keep it at the very top of the file.
The class, and the name that must match. Step two, the class. Directly below the header comment, declare a class that extends PM_Plugin, and give it a title. That is a complete, valid plugin. It does nothing yet, but PageMotor can load it and activate it. One thing to be careful about: the class name must match the Class field in the header exactly. PageMotor instantiates the class by reading that header, so a typo in either place means the plugin simply will not load.
construct, then init. The base class gives you two override slots for your own start-up code. Construct runs early, before your settings are loaded: use it for database setup, includes, anything that has to exist before the rest. And init runs once your valets are registered and your settings are loaded: use that for work which depends on them. There are also two you must leave alone. __construct() and _init() are framework-owned. Those two are not yours to touch.
Add a capability. Step three, adding an actual capability. To register a shortcode, implement the shortcodes valet. It returns an array mapping shortcode names to method names on your own class. Prefix the shortcode name, as you did the folder, because the first plugin to claim a name wins it. Then write the handler. It receives any attributes as an args array, escapes them with PageMotor's own text method, and returns its HTML. Note that word: returns. It does not echo. Get that the wrong way round and your output jumps to the wrong place on the page.
Shortcodes need css_sitewide(). Now the second thing that catches people, and it is worth knowing before it costs you an afternoon. If your shortcode needs its own CSS, register it with css_sitewide(), not plain css(). The plain one only loads when an instance of the plugin has been placed in the current page template, which is exactly right for Blocks and Containers. But a shortcode can appear on any page at all. So its styles have to be sitewide, or they will be missing precisely where you did not think to test.
Activate it, then use it. Steps four and five. Put the folder on the server, then in the admin go to Plugins. Yours appears in the list under the Name from your header. Tick the box beside it and click Save Plugins. That activates it: the class is loaded, and its valets run on every page load. Uploading the folder on its own only lists it. Or, if your AI is connected to your site over MCP, it can install the plugin and switch it on for you, with no server login at all. Then edit any page, drop the shortcode into the body, and save. Shortcodes run in page content, not in an uploaded HTML document, so if your output does not appear, check what you are editing before you go looking through your code.
A crash still costs you. And one last thing, which is the reason to keep early plugins simple. PageMotor includes your plugin file directly. If the file crashes while it loads, that request fails, and PageMotor switches the plugin off and tells you so in the admin. But a crash inside your shortcode handler is not caught: every page that uses it breaks until you fix it. Work with a safety copy, test each change as you make it, and if something breaks, fix the file before you do anything else.