Package Development Guidelines

These guidelines apply to every Marketpath CMS package. They aim for packages that are small, predictable, and safe to install and update on sites you do not control. Marketpath Site Standards 1 (MPSS1) builds on them, so a package that follows MPSS1 should also follow these guidelines.

Most advice for building any site or component well, packages included, is in Development Practices. This page covers what is specific to the package manager: names and types, install behavior, organization, documentation, rights, and publishing.

Packages should have descriptive and unique names. For asset organization it helps for a package with a long name to also have a unique shortened identifier (for example, "Personal Portfolio Site" by Marketpath becomes "mp-pps1"). Paths follow Asset Names and Paths.

Standard label. Where applicable, a package should conform to a predefined set of standards and identify it with a label whose key is "standard". For Marketpath Site Standards 1 the value is "mpss1" (standard:mpss1), or a framework-specific code when the package applies only to a framework that has its own variant (standard:mpss1-bootstrap5; see MPSS1 Framework Variants). Each full site package should have a single standard: sites created from the package use it to find page packages to install, so do not put both standard:mpss1 and standard:mpss1-bootstrap5 on the same full site package. Packages that share a standard can guarantee interoperability to the greatest extent reasonably possible.

Dependencies. A package that follows MPSS1 may depend on packages that are not MPSS1 packages, such as data, component, or widget packages, as long as they are also consistent with the interoperability rules in the standard.

Wherever possible, break large packages into smaller component packages. This centralizes the creation and maintenance of components used by many packages, which improves both the quality and the build time of new sites and packages. It only works if each package used is high quality and follows these guidelines. Only assets specific to the current package should be unique to it.

Full site
• Use only for packages that can and should be installed when a site is first created. A full site package must also follow the full site requirements below.
• Generally includes numerous packages of every other type (but no other full site packages), plus every asset on the site that is not part of another package.

Page
• Use for packages with a small number of page templates (ideally one, though bundling several sometimes makes sense) and their related assets such as javascript and stylesheets. Keep them as lightweight as possible while still complete.
• Do not include sample pages. Describe the sample on the package's demo or documentation page instead, which keeps the package reusable inside full site packages.
• Generally includes several widget packages, and possibly others.

Widget
• Use for packages that add a visible widget to a site, such as pagination, a banner, a CTA, a blogroll, or a tag cloud. A widget does nothing on its own; another template must include it, usually with some configuration, before it outputs anything.
• Typically includes one or more component packages, and possibly a data package.

Form
• Use for packages with a small number of form templates (ideally one) and their related assets. Keep them as lightweight as possible while still complete.
• Do not include a sample form. Describe it on the package's demo or documentation page instead.
• Generally includes one or more component packages.
• Test form templates with every field type, condition, and validation option.
• Form packages should generally auto-update by default, which makes form maintenance easier for everyone. That also means a form package must not be updated until the update is thoroughly tested.

Gallery
• Use for packages with a small number of gallery templates (ideally one) and their related assets. Keep them as lightweight as possible while still complete.
• Do not include a sample gallery. Describe it on the package's demo or documentation page instead.
• Generally includes one or more component packages.

Data
• Use for packages of reusable data or configuration, such as a reusable datastore definition, a reusable list of objects (for example, US states), or a snippet to include in the header or footer of many sites.
• Does not typically include other packages, and includes only the fewest assets its purpose needs.

Component
• Use for packages of reusable building blocks such as partials and javascript libraries. A component does nothing on its own; it must be used according to its instructions. Ideally each component package accomplishes a single purpose.
• May include other component or data packages, but is often the smallest unit, containing only the assets and packages its single purpose requires.

Full site packages carry extra requirements because every site created from them starts with their contents. They should also follow Development Practices and cover what Production Readiness lists, including a complete set of page templates, a sitemap, and a robots file. A full site package should carry one MPSS1 standard label (Package Naming and Standards).

Marketpath branding
Although it is not enforced for third-party themes, every site's footer should include "Powered by Marketpath CMS", linked to https://www.marketpath.com, optionally with the Marketpath logo in place of the words "Marketpath CMS".

Clean
Sites commonly contain old assets that are no longer used. Before creating a full site package, trash old assets so new sites do not start with extra clutter. Find candidates under All Content, Filters, Not Referenced. Some unreferenced items are fine (robots.txt, sitemap.xml, landing pages), and some content is pulled in dynamically by templates (for example, images by tag), so do not trash everything listed. Also review menus, snippets, image presets, custom site settings, and custom profile settings.

Domains
A full site package should have a single active domain, typically a development domain. Multiple domains on the source site are combined into one when the package is installed on a new site.

A site is easier to maintain with a clear organizational structure. Use folders and paths that make sense, are intuitive, and are consistent between assets, packages, and sites.

Sample content and install-only content
• Start the Name (not the Title) of all sample content with "SAMPLE: " unless it must be named differently for a specific reason.
• Place sample content under a folder called "samples", and sample images under "samples/images", unless they must be elsewhere for a specific reason.
• Include content that is not central to the package's function as Install Only, so editors can change it without fear that an update will overwrite their changes, and so updates stay simple. This applies doubly to folders.
• Wherever possible, restrict folders and templates to specific entity types so users find the right folder or template while creating content. Also set default root paths for folders, blogs, and datastores, and set default templates, such as the template for blog posts.

Package asset paths
Organize templates, javascript, and stylesheets by company, package name, and asset type, on top of the conventions in Asset Names and Paths.
• Start every path with your lowercase company name (for example, "marketpath") followed by the package identifier (for example, "mp-pps1").
• If a package includes more than one version, follow the package identifier with the version number. Including a version number in the first release often makes future updates easier.
• Do not change names or paths once the package is activated; Asset Names and Paths gives the rule and how to ship a breaking change. In a package, also set the original asset to Ignored and note the breaking change, with where to find the new assets, in the package changelog.

Examples:
• /marketpath/superbanner/v1/_banner.liquid
• /marketpath/superbanner/v1/js/mpbanner.js
• /marketpath/superbanner/v1/js/_mpbanner.js
• /marketpath/logisticall/home.liquid
• /marketpath/logisticall/contact.liquid
• /marketpath/logisticall/_sidebar.liquid
• /marketpath/logisticall/_menu.liquid
• /marketpath/logisticall/css/main.scss
• /marketpath/logisticall/js/main.js

Consider keeping overrides under a different root path, for example /overrides/marketpath/superbanner/v1.

Documentation
Each package should have:
• A publicly accessible documentation page for developers
• Site Instructions for editors, if applicable
• A publicly accessible demo page, if possible
In particular, note any functionality that uses custom or core site settings, because those values must be reviewed and set deliberately after the package is installed.

Customization
A package must be customizable without overriding its core assets (assets set to Install and Update). Its documentation should state clearly how the package can be customized without overriding core assets.

Sometimes that means passing configuration variables into components. Other times it means install-only assets, such as template and variable override files. Wherever possible, provide default values even when nothing is passed in or overridden. That makes components more robust and package updates smoother.

Rights
A package must not include any asset you do not have the right to distribute to everyone with access to the package, so public packages cannot include assets that are not free for commercial use. When you do have the right to distribute content such as scripts or images, document it in the code and follow any other requirement set by the owner. Double-check that you have permission to distribute every image, document, and other copyrighted content in each package before activating it.

License files
Include every license file and other asset that the original source requires. Place them as a template inside your root package path. If the asset has no name or extension, give it a descriptive name with a .txt extension, for example /marketpath/foundation6/LICENSE.txt. License and other ancillary assets do not need to be published unless end users must also be able to read them.

Agreements
If terms must be explicitly agreed to before the package is installed on a site, include those terms in the package agreement. Do not include agreements for child packages in the parent package; users agree to child packages when they are installed. A package should not need more than one agreement. If it requires agreement to several sets of terms, split it into separate packages with their own agreements.

• Confirm the package's purpose and target, and that it has a single purpose (Package Types explains how to split a large package).
• Use the two-partial structure, a base partial and an editor partial, where the package has editor fields (see Template Practices).
• Document it: its purpose, install prerequisites (for example MPSS1 and Bootstrap 5), fields, examples, known dependencies, and a demo URL.
• Plan for site-level overrides versus automatic updates, and document breaking changes for each version.
• Test a fresh install on a clean MPSS1 site alongside common packages (navigation, hero, testimonials, maps), and check that nothing collides.
• When publishing broadly, request approval through the official process (see the Package Approval FAQ).

• 2026-10-30: The free plan compatibility requirement was removed from Full Site Package Requirements because the free plan is retired. The standard label and dependency guidance moved here from MPSS1, which now sits beside Development Practices in Building Sites. The checklist of site objects became Production Readiness.
• 2026-10-21: The code, template, asset name and path, quality and accessibility, and editor experience guidance moved to Development Practices, reworded for every site and component. Rights and agreements, and a pre-publish checklist, became sections of this page, and Best Practices for Package Creation was folded into it.
• 2026-09-16: Moved from the Guidelines & Standards article into the Building Sites documentation. The guidance is unchanged; template comment and variable scope rules now point to the template guidance in Development Practices and to Variable Scopes, the accessibility list names Bootstrap's current visually hidden classes, and typos and headings were cleaned up.
• 2025-04-24: Added a short section about output validation.
• 2023-03-14: Recommended restricting page templates to a single entity type and adding a representative image.
• 2023-01-12: Added Repeated Content and Default Values under the editor experience, and multi-lingual guidance under customization.