Static Pages
A static page is a plain .html file in your project’s pages/ directory. lps page push turns each file into a WordPress page (post_type=page) whose slug is the file name: pages/legal-notice.html becomes /legal-notice/ on a site using pretty permalinks, or a ?page_id= URL on Plain permalinks. Either way, use the URL lps page list reports rather than assuming the pretty form. The page is rendered inside your active theme, header and footer included, classic and block themes alike.
pages/home.html is the exception: it becomes the site’s front page, served at /. Once its status is publish, pushing it sets Settings > Reading to “A static page” with this page as the homepage, replacing whatever the site showed there before (its latest posts, or another page), and the push says so. A draft home.html is pushed like any other page but never becomes the front page, so visitors never land on an unpublished home. Switching it back to draft while it’s the front page reverts the site to showing its latest posts.
The file is the only source of truth. A page pushed by Loopress can no longer be edited in wp-admin, so what’s in Git is always what’s on the site.
File format
Section titled “File format”<!--title: Legal noticestatus: publish--><section class="legal"> <h1>Legal notice</h1> <p>...</p></section>The file may start with an HTML comment of key: value lines. It stays valid HTML, so you can open the file in a browser to preview it. The header is removed from what gets pushed.
| Key | Default | Description |
|---|---|---|
title |
Derived from the slug (legal-notice → Legal notice) |
The page title, used by the theme and in <title>. |
status |
draft |
draft or publish. Declarative: switching a published page back to draft unpublishes it on the next push. |
full-width |
false |
true or false. On a block theme, drops the theme’s max-width and side padding for this page’s content only, including the padding of the template’s own wrappers around it (header and footer keep theirs). Horizontal only: the space the template leaves above and below the content stays, use your own page template to remove it. Silent no-op on a classic (non-block) theme. |
hide-title |
false |
true or false. Hides the theme’s own page title block, useful when your HTML already has its own heading. Same block-theme-only scope as full-width. |
template |
Theme default | A template slug the active theme offers for pages: one it ships (a block theme’s templates/<slug>.html, or a classic theme’s page-<slug>.php), or one of your own templates. WordPress refuses an unknown slug, and the push of that page fails with Invalid page template. |
Any other key, or any other status, is rejected before anything is sent to WordPress, so a typo never silently falls back to a default.
File names must be lowercase letters and digits separated by single hyphens (legal-notice.html, not -legal--notice.html): WordPress would rewrite such a slug and the page would no longer match its file. Only .html files are allowed in pages/ (dotfiles such as .DS_Store are ignored), and subdirectories are not supported yet: one file per page, at the top of the directory. A file that breaks any of these rules stops the whole push before any network call.
The directory is pages/ by default, set pageDir in loopress.json to change it.
Templates and parts
Section titled “Templates and parts”On a block theme, your project can also version the theme’s templates and template parts, as .html files of block markup (what the Site Editor saves): theme/templates/<slug>.html and theme/parts/<slug>.html, next to the Global Styles file.
lps theme template push writes them as the files of a child theme of your block theme, named after it with a -loopress suffix: twentytwentyfive-loopress, “Twenty Twenty-Five Loopress”. That’s the way WordPress expects a site to override a theme: the parent theme stays untouched and keeps receiving its updates, and everything the child doesn’t override still comes from the parent.
theme/templates/single.html → twentytwentyfive-loopress/templates/single.htmltheme/templates/bare-landing.html → twentytwentyfive-loopress/templates/bare-landing.htmltheme/parts/header.html → twentytwentyfive-loopress/parts/header.html-
Any template of the template hierarchy:
single,single-post,archive,category-news,taxonomy-download_tag,page-no-title… WordPress resolves the name. Override a parent template by using its name, or add your own. -
Your own page templates: a template with a header becomes a custom template a page can pick with its
templateheader:theme/templates/bare-landing.html <!--title: Bare landingpostTypes: page--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-content /--></main><!-- /wp:group -->pages/launch.html <!--status: publishtemplate: bare-landing--><section class="hero">...</section>This one has no header or footer part, so
launchrenders as a bare page. -
Header keys. Templates:
title(the name in the template picker) andpostTypes(comma-separated,pageby default). Parts:title(derived from the slug) andarea(headerforheaderorheader-*,footerforfooterorfooter-*,uncategorizedotherwise). Loopress turns them into the child’stheme.json(customTemplates,templateParts), keeping the parent’s own entries. A file that opens on a block (<!-- wp:... -->) has no header. -
No
themeattribute on a template part.<!-- wp:template-part {"slug":"header","theme":"twentytwentyfive"} /-->makes WordPress load the parent’s header and ignore yours, so the push refuses it. Write{"slug":"header"}. -
The child mirrors the project. Every push rewrites it whole: a file you delete locally is removed from the child, and the parent’s version comes back.
-
The child is activated only when you ask. WordPress stores some settings per theme (menu locations, logo, widgets, Global Styles), so the push never switches themes on its own. Run
lps theme activateonce, or set"activateChildTheme": trueinloopress.jsonso everylps theme template push(and solps push) activates it when it isn’t. A child without settings of its own starts from a copy of its parent’s theme mods and Global Styles. Until it’s active, the push warns that nothing changed on the site. -
Edits made in the Site Editor are saved by WordPress in the database, and that copy wins over the child’s file. They’re never overwritten:
lps theme template diffandlps diffreport them as drift (siteEditor: "customized"), andlps theme template pushwarns about them. Use Clear customizations in Appearance > Editor to go back to the pushed file. -
Shortcodes don’t see the posts of a Query Loop. WordPress runs every shortcode of a template once, on the whole file, before it renders any block. A
[price]inside awp:post-templateis replaced before the loop exists, so it shows the value of the page’s own post for every item. For a value per item, use a block binding (WordPress 6.5+) registered in a hook, withuses_contextso it receives each item’spostId:register_block_bindings_source('my/price', ['label' => 'Price','uses_context' => ['postId'],'get_value_callback' => fn(array $args, WP_Block $block) => my_price($block->context['postId']),]);<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"my/price"}}}} --><p></p><!-- /wp:paragraph -->Dynamic blocks that read the current post when they render work in a loop as they are.
-
Requires a block theme as the active theme (or the Loopress child itself). Another child theme can’t be extended, WordPress has no grandchild themes.
File names are lowercase letters, digits, _ and -, the characters of a post type or taxonomy slug (taxonomy-download_tag.html). Same directory rules as pages otherwise. The directories are theme/templates/ and theme/parts/ by default, set templateDir and partDir in loopress.json to change them. lps push pushes templates and parts before pages, so a new page can use a template pushed in the same run.
Theme CSS
Section titled “Theme CSS”The same push bundles your theme’s CSS into the child theme, with esbuild, and the plugin loads it with WordPress’s own functions. Two folders, two ways of loading:
theme/css/style.css → twentytwentyfive-loopress/style.css, on every pagetheme/blocks/core/button.css → twentytwentyfive-loopress/blocks/core/button.css, only where a button renders-
theme/css/style.cssis the entry. It@imports the other files oftheme/css/in the order you want, which is the cascade order. Split it the way you like, one file per component works well (BEM, for example):theme/css/style.css @import "./reset.css";@import "./layout.css";@import "./c-card.css";CSS files without a
style.cssto import them are refused, nothing would load them. -
theme/blocks/<namespace>/<block>.cssstyles one block, named like the block:core/button.css,core/navigation.css,woocommerce/product-price.css. WordPress only prints it on a page that renders that block (wp_enqueue_block_style()). A block style variation such asis-style-outlinegoes in its block’s file. The push warns about a file named after no block registered on the site: a typo, or a block from a plugin that isn’t active there. -
Bundled.
@importis resolved, a relativeurl()to a font or an image is copied to the child’sassets/and rewritten, and the result is minified. Absolute URLs are left alone. Sass and vendor prefixes aren’t part of it: native CSS nesting and custom properties cover most of what they did. -
Loaded on the site and in the editor, once the child is the active theme. A small stylesheet is inlined in the page instead of costing a request. Every push changes its version, so browsers never keep a stale copy.
-
Classes without a block of their own go in
theme/css/. A.c-cardtyped in the Additional CSS class field of a Group has nothing for WordPress to load it on. Same for blocks on nearly every page (core/group,core/paragraph): their file loads everywhere anyway. -
Content loaded later can miss its block CSS. A block rendered by a shortcode gets its CSS at the end of the page, so it can show unstyled for a moment. Content loaded with JavaScript (AJAX, REST) never gets it. Move that CSS to
theme/css/. -
Colors, fonts and spacing belong in Global Styles first: WordPress turns them into CSS variables you can use here.
The directories are theme/css/ and theme/blocks/ by default, set cssDir and blockCssDir in loopress.json to change them.
Commands
Section titled “Commands”Every command below also accepts the common flags: --env, --json, and --yes where it applies. Pages and templates have no pull: the files in Git are the source of truth.
lps page push
Section titled “lps page push”Push every page, or only SLUG. Supports --dry-run and --overwrite.
lps page pushlps page push legal-noticelps page push about --overwriteTaking over an existing page
Section titled “Taking over an existing page”When a page with the same slug already exists on WordPress but wasn’t created by Loopress (you’re rebuilding your current /about/ page as a file), the push lists those pages and asks once whether to take them over. Without a terminal to ask in (CI, the MCP server), they count as failed unless you pass --overwrite.
Taking over keeps the page’s URL and ID, so its menu items, internal links and SEO plugin data keep working, which deleting it in wp-admin and pushing a new one would break. From then on the page shows your file and is locked in wp-admin like any Loopress page. Its original content is saved as a WordPress revision first, unless your site disables revisions. --dry-run doesn’t detect these pages, only the real push does.
lps page list
Section titled “lps page list”List the pages managed by Loopress on WordPress, with their status and URL.
lps page diff
Section titled “lps page diff”Show what differs (HTML, title, status and the other header fields) between pages/ and WordPress. Also part of the aggregate lps diff (--only page).
lps page rollback
Section titled “lps page rollback”Put back the pages the last lps page push changed, as they were before it: HTML, title, status and header. A page that push created is not removed, the command lists it. See Rollback for --list, --to and --dry-run.
lps theme template push
Section titled “lps theme template push”Write every template, part and the theme CSS to the Loopress child theme. Supports --dry-run. Refuses with “Nothing to push” when the project has no template, part or CSS directory.
lps theme template list
Section titled “lps theme template list”Show the child theme: active or not, its templates and parts, and those edited in the Site Editor.
lps theme template diff
Section titled “lps theme template diff”Show what differs between theme/templates/ + theme/parts/ and the child theme, Site Editor edits included. Also part of the aggregate lps diff (--only template, --only part).
lps theme template rollback
Section titled “lps theme template rollback”Put back the child theme the last lps theme template push replaced. Like the push, it mirrors: a template or part that push removed comes back, one it added is removed. See Rollback for --list, --to and --dry-run.
The site only knows a hash of each CSS file, so the snapshot keeps the CSS bundle each push sent. The CSS before a push is restored when it is the bundle of the previous push from the same machine, or when the site had no CSS. Otherwise (the first CSS push from this machine, CSS pushed from somewhere else since), the rollback keeps the CSS that push sent, and says so. Activating the child theme (activateChildTheme) is not undone.
Pages and templates are also part of lps push, lps diff, and lps dev (a saved file is pushed to your local environment right away).
When several pages are pushed, each one is pushed on its own: a refused page doesn’t stop the others, and the command fails at the end with the number of pages that failed.
What gets refused
Section titled “What gets refused”The push is refused, and nothing is written, when:
- a page with the same slug already exists on WordPress but wasn’t created by Loopress, unless you take it over.
- the Loopress page is in the trash. Restore it manually in wp-admin before pushing it again.
- the slug is already used by another page, a media file, or is reserved by WordPress. WordPress would otherwise rename your page to
about-2behind your back. Rename your file. - the HTML is over 512 KB, or all managed pages together are over 8 MB. Both limits can be raised with the
loopress_max_file_bytesandloopress_max_files_total_bytesfilters (the second argument is'pages').
In wp-admin
Section titled “In wp-admin”In Pages, a page pushed by Loopress carries a Managed by Loopress badge and has no Edit or Quick Edit link: the editor, Quick Edit and bulk edit are closed for it, including its slug, status and template, all of which come from the pushed file instead. You can still:
- add it to a menu;
- move it to the trash. The next push then refuses it until you restore it;
- preview a
draftpage: the Preview row action opens the real rendered page, the same read-only check WordPress’s own front-end draft preview uses.
Because the editor is closed, the SEO plugin’s meta box and the featured image are not reachable for these pages either.
How it renders, and known limits
Section titled “How it renders, and known limits”The HTML is stored in a hidden post meta, never in the page’s regular content (post_content, which stays empty). It is inserted through the the_content filter, before shortcodes and embeds run, so shortcodes, oEmbed links and image lazy-loading work as on any page. Automatic paragraphs (wpautop) are turned off for these pages only, your markup is output as written.
- Shortcodes from other plugins may lose their styles. Many plugins decide whether to load their CSS and JS by looking for their shortcode in
post_content. Since it’s empty, the shortcode renders but without its assets on those plugins. Plugins that load their assets from the shortcode itself are not affected. - Bare pages need a block theme. A page is rendered inside its template. For a page without the theme’s header and footer, push a template that leaves them out. Classic themes have no such option.
- WordPress search matches a page’s title, not its HTML. Core search includes
post_title, so a page can turn up by title, but it never matches inside the pushed HTML, since that lives outsidepost_content. - Deactivating Loopress leaves these pages empty between the theme’s header and footer. Nothing leaks, and
lps doctorreports the missing plugin. - Pushed HTML is not filtered. Like API routes and hooks, anything you push,
<script>included, runs on the site as is. Pushing requires an administrator (manage_options) account. - There is no
lps page pullorlps page rmyet: to remove a page, trash it in wp-admin and delete its file.