Best Practices for Package Creation
Practical habits for building Marketpath packages that are interoperable, simple, reusable, editor-friendly, and aligned with MPSS1.
These practices apply the Package Development Guidelines and MPSS1 day to day, with a focus on interoperability, simplicity, reusability, editor-friendly design, versioning, accessibility, and QA.
Core Principles
Interoperability first, one responsibility per package, editor-friendly design, and standards-based Liquid.
• Interoperability first. Align with Marketpath Site Standards 1 (MPSS1) so packages work together across sites, with the aim to guarantee interoperability of packages to enable rapid, high-quality website development.
• Simplicity and single responsibility. Prefer small, focused packages. If complexity is unavoidable, split it into components with clear dependencies and document them.
• Editor-friendly by design. Separate rendering logic from editor inputs so sites stay maintainable as content grows.
• Standards-based Liquid. Use Marketpath Liquid syntax, filters, and objects exactly as documented to avoid runtime surprises.
Package Structure and Naming
The two-partial pattern, consistent package names, and when content belongs in a datastore instead of on the page.
Two-partial pattern (recommended):
• Base partial: no editor fields; pure rendering and logic.
• Editor partial: only the editor fields; it turns them into variables and passes them to the base partial.
This lets you swap fields without touching rendering logic, and reuse the base partial where the data comes from code instead of fields.
Consistent naming:
• Prefix by domain and responsibility (for example nav-bootstrap5, banner-hero, cards-testimonials).
• Keep one clear entry partial per package.
Data modeling:
• Rule of thumb: if uses outnumber variants by more than 3 to 1, centralize the content in a datastore; otherwise use a fieldset or inline fields on each page. For example, 3 CTA variants used across 9 or more pages belong in a datastore.
• If the package uses a datastore and can have multiple variants, create a separate core package for the datastore (such as a Services Data Store package).
Composition and Dependencies
Keep one purpose per package, map shared libraries at the site level, and target MPSS1 variants.
• Give each package a single purpose; break components out and connect them with explicit dependencies only when necessary.
• Map commonly shared libraries (for example Bootstrap 5) at the site or theme level when possible.
• Bundle truly unique assets inside the package so it stays portable. Decide deliberately during package design.
• Minimize dependencies so packages are easier to install, version, and update.
• Target MPSS1 variants (for example mpss1-bootstrap5) to maximize plug-and-play adoption across public templates.
Liquid and Templates
Use documented Liquid, know how the page and html objects behave, and keep transformations out of editor-facing markup.
• Use documented Liquid syntax and filters for conditionals, variables, and date and formatting utilities, such as {% if %}…{% endif %}, {% var %}, | date, and | capitalize.
• Know how objects like page, document, and html behave, and the special <liquid-markup> tag, which is evaluated once in HTML fields.
• Avoid side effects in editor-facing markup. Keep transformations in the base partial whenever possible, which pairs well with the two-partial pattern.
Editor Experience and Reusability
Expose only the fields an editor needs, build landing pages as Articles, and tag consistently.
• Field hygiene: expose only essential, well-labeled fields (a unique prefix can help), and turn them into clean variables before calling the base partial.
• Landing pages: build them as Articles with a datastore item list field to select and order items, so datastore records carry no layout responsibilities.
• Tagging: use Marketpath tags consistently, on the site, in the management UI, or both, for filtering and collections.
Versioning, Updates, and Approval
Plan for site-level overrides versus automatic updates, document breaking changes, and use the approval process.
• Follow the Marketpath package version and update model, and plan for site-level overrides versus automatic updates. Document breaking changes for each version.
• Align with the Package Development Guidelines and request approval through the official process when publishing a package broadly.
Documentation and Demos
Publish a short public document for every package, with prerequisites, fields, examples, and a demo URL.
Publish a short public document for every package: its purpose, install prerequisites (for example MPSS1 and Bootstrap 5), fields, examples, known dependencies, and a demo URL.
Accessibility, Performance, and QA
Semantic HTML, keyboard and contrast testing, consistent image presets, and a smoke test on a clean MPSS1 site.
• Use semantic HTML, and test keyboard navigation and color contrast.
• Optimize images, using consistent presets and ratios across the UI. Presets such as square thumbnails and 16:9 widescreen keep rendering predictable.
• Smoke-test installs on a clean MPSS1 reference site, and verify there are no collisions with common packages such as navigation, banners, testimonials, and maps.
Checklist
The short list to run before you publish a package.
• Confirm the package's purpose and target.
• Implement the two-partial structure (base and editor).
• Provide at least a demo URL, and possibly a documentation page.
• Test a fresh install on a clean MPSS1 site with common packages (navigation, hero, testimonials).
Best Practices Revision History
Dated changes to Best Practices for Package Creation.
• 2026-09-21: Split into sections so the page carries an on-page contents list, matching Package Development Guidelines and MPSS1. The practices are unchanged.
• 2026-09-16: Moved from the Guidelines & Standards article into the Building Sites documentation. The practices are unchanged.