README

Municipio Theme Extensions adds focused theme compatibility options that are missing from modern Municipio. It does not add editorial workflows or business functionality.

The plugin supports modern Municipio only. Municipio LTS is a migration source, not a supported runtime.

Installation

Install the package with Composer:

composer require municipio/wp-plugin-municipio-theme-extensions

The package type is wordpress-plugin, and extra.installer-name ensures that composer/installers places it in wp-content/plugins/municipio-theme-extensions. Activate Municipio Theme Extensions in WordPress after installation.

Header settings

The first release adds two fields to Municipios existing Header → Appearance section:

header link color;
header link size and weight.

The fields target links and icons shown directly in the header. Header trigger buttons, drawer navigation, other menus, and Municipio markup remain owned by Municipio. The configured color also applies to hover, focus, active, and visited states so generic link colors cannot reduce header contrast.

For the standard header, the plugin also restores the saved header_breakpoint, tab_menu_button_size, and hero_search_placeholder settings in Municipios existing Header layout, Tab menu, and Search sections. Unsaved installations keep Municipios current lg, sm, and generated-placeholder defaults.

The release also adds Letter Spacing as a subfield in Municipios existing Typography → Button control. The value is stored with the other typography_button choices and writes --letter-spacing-button, which a plugin rule uses to override the fixed spacing on Municipios small buttons without replacing its Blade markup. The default preserves Municipios current .1rem; migrated LTS button typography uses normal because the former Municipio Extended button template did not apply that spacing.

Secondary menu behavior

The plugin adds Start secondary menu at level two to Municipios existing Menu → Behaviour section. The setting is enabled by default and removes the active level-one branch from the secondary sidebar navigation even when the primary menu has no assigned items. Disabling it restores modern Municipios current behavior for that configuration and displays the complete tree.

The option uses Municipios controller applicator and its cache. The runtime default matches the field default, so existing installations receive the enabled behavior without an activation migration or an initial Customizer save. Primary, mobile, drawer, mega-menu, and breadcrumb data are not modified.

Drawer palette

The plugin extends Municipios existing drawer controls with a Light choice for both the main area and the optional secondary area. The choices retain Municipios setting names, modifier output, markup, focus handling, and responsive behavior. Their presentation uses the site's --color-background token with dark text, links, and icons.

Neither choice is a new default. New Municipio sites therefore retain Municipios standard drawer palette until an editor selects another value. LTS migrations can explicitly select both light values through their migration tooling without making plugin activation mutate site data.

Below-title secondary navigation

The plugin also adds Below title to Municipios existing secondary navigation position field for supported Municipio versions from 6.43.3 up to, but not including, 8.0.0. On singular hierarchical posts, this mode renders published direct children in menu order after the article heading and before the regular content. Hidden menu items are excluded, and links use Municipios current secondary Button color.

The existing secondary_navigation_position=below_title theme mod and page_hide_secondary_menu post metadata are reused without writing or backfilling data. The page field is registered with its legacy key and name only when Municipio or another plugin does not already own an equivalent field. Pages without eligible children produce no navigation wrapper. The navigation wrapper exposes the stable municipio-theme-extensions-below-title-navigation class so site-specific themes can style this presentation without depending on utility classes.

One Page classic content

The plugin restores the LTS-compatible Display text content for One Page template option in Municipios existing General settings section. It reuses the municipio_customizer_onepage_body_text theme mod, promotes the current One Page title when enabled without overriding the static front page's page-level title choice, and lets Municipios own template render filtered classic content through the same content branch used for blocks. No page template or content is copied or migrated.

Content layout

The plugin restores the three legacy content-layout settings inside Municipios existing Page width section: the default width for modules set to inherit, placement of the content module area inside or outside the article, and left or centered article content. Existing mx_default_module_width, mx_content_area_placement, and mx_article_alignment theme mods are read without migration or activation writes.

Unsaved settings use the legacy defaults grid-md-12, outside, and left. Only an empty inherited Modularity width is replaced; explicitly saved widths remain untouched. Inside placement reuses Municipios article hook and sidebar partial and is limited to regular single and page-centered templates so One Page, archives, and other rendering paths retain their current behavior. Centered readable articles fill the available column and remain capped by Municipios --container-width-content value, including values changed through the theme's width setting.

Activation migration

Activation runs a versioned, idempotent migration for the settings needed by the first release:

compatible color values are reused directly;
legacy header_color tokens are mapped to explicit colors;
the existing primary-navigation contrast color is used as a fallback;
button font size and weight are copied to the new header-specific typography setting;
reusable LTS button typography receives normal letter spacing without overwriting an explicitly configured value.
legacy desktop search placements are complemented with their current mobile equivalents when legacy-only header settings prove that the selection came from LTS.

Existing target values are never overwritten. Legacy theme mods remain in the database for troubleshooting and rollback, and the completed migration version is stored in municipio_theme_extensions_migration_version. The version check also runs after theme setup so an active Composer-installed plugin applies new migrations without a deactivate-and-reactivate cycle.

Development

Migration development and release cleanup follow the canonical policy in docs/migrations.md. Unreleased migration iterations are squashed into one schema version per package release; released migrations are retained until their source versions are no longer supported.

composer install
composer test
composer lint

municipio / wp-plugin-municipio-theme-extensions

Package info

Security

Statistics