Packages should have descriptive and unique names. For the purpose of asset organization it is helpful for packages with a long name to also have a unique shortened version of that name (eg: “Personal Portfolio Site” by Marketpath -> “mp-pps1”) for use as an identifier. For the sake of consistency we recommend using kebab-case for all paths.
Where applicable, packages should conform to a predefined set of standards, which should be identified using the “standard” label (eg: “standard:mpss1-bootstrap5”). This is useful for guaranteeing interoperability to the greatest extent reasonably possible between packages utilizing the same standard (see our MPSS1 documentation for an example of what that standard might look like).
Wherever possible, large packages should be broken down into smaller component packages. This centralizes the creation and maintenance of components used in multiple other packages - which should improve both the quality and buildout time of new sites and packages. Of course, each package used should be high-quality and must also follow the Marketpath package development guidelines or this will not work. Only assets specific to the current package should be unique.
Full site packages should include common UI components in the form of partial templates that will make it easier for developers to make changes and add new sections to the site. Ideally these common comon components would come from reputable packages but some may be custom for the current site. Some examples of common components include:
One common way to implement this is to create two templates initially - one for the UI component that takes the raw data as input and a second template to fetch the data and include the UI component template.
Full site packages should have everything that a developer needs in order to get started. This means, at a minimum:
Although it will not be enforced for third-party themes, Marketpath branding should be included on every page using the {% powered_by %} template method in the footer. This has a number of benefits, including:
Note that attempts to modify, remove, hide, or obscure the Marketpath Branding will constutute a violation of the Marketpath terms of service and could result in punitive action by Marketpath. Such actions may additionally result in the branding automatically being re-displayed even more prominently.
It is also permissible for the developer of a theme to add their own branding to the footer of theme sites, although there are currently no specific guidelines to how they may or may not go about this, other than that they may not place javascript or other content on the site that may reasonably be deemed inappropriate or malicious by Marketpath or by other users (eg: tracking scripts or pixels).
It is common for sites to contain old assets that are no longer used. Before creating your full site package, try to clean up (trash) old assets so that when new sites are created using your full site package they do not start with a lot of extra junk to sort through.
These can be identified by navigating to All Content -> Filters -> Not Referenced. Sometimes it is OK for a page to be unreferenced (eg: robots.txt, sitemap.xml, and landing pages) and sometimes content is pulled in dynamically from the template (eg: images by tag) so not everything that is listed as not referenced should be trashed.
Additional items that should be reviewed to see if they are still needed include menus, snippets, image presets, custom site settings, and custom profile settings.
Part of keeping a clean site also means making sure that “Include in Search” is set properly for all pages. This should be checked for most pages but should be unchecked for any pages that should not be displayed in on-site search results (eg: meta pages, private pages, thank-you pages, dynamic pages based on query parameters, etc…). For pages that do not have "Include in search" checked, the Meta Robots field should be set properly as well - which for most will mean setting it to "noindex, nofollow".
Full site packages should only have a single active domain - which will typically be a development domain. Multiple domains on the source site will be combined into a single domain when it is installed on a new site.
If a theme is a contender to be a free site, then we need to take extra care that it has less than 20 pages (URLs).
Things that can help keep the number of pages down:
The 20 page limit should be sufficient for very simple sites, but if you find yourself struggling with the limit then you may need to consider if the site really should be a free or a paid site. If you are creating a paid full site package, contact Marketpath to be able to go live with the source/demo site for free!
All themes should be styled using scss or less and should utilize customizable variables wherever possible (most importantly for colors and font styles), which should make the theme easier to customize for the sites that are build with it.
Typically via responsive markup, but may be accomplished using other means if desired. Mobile-first design is preferred but not required. All relevant components must be checked for mobile responsiveness.
It is easier to maintain a site with a clear organizational structure. Use folders and paths that make sense, are intuitive, and that are consistent between assets, packages and sites.
The names for all sample content should start with “SAMPLE: “ (Name, not Title) unless they must be named differently for a specific reason.
Place all sample content under a folder called “samples” unless they must be in a different folder for a specific reason. Place all sample images in “samples/images” unless they must be in a different folder for a specific reason.
Content that is not central to the functionality of the package should be included in the package as “Install Only” in order to make it as easy as possible for content editors to make changes without fearing that their changes will be overwritten or make package updates more complicated than necessary. This applies doubly for folders.
Wherever possible, restrict folders and templates to specific entity types. This makes it easier for users to find the desired folder/template while creating and managing content. Also include and enforce default root paths for folders, blogs, and datastores; and set the default template for blog posts etc…
Templates, javascript, and stylesheets should be organized according to the company, package name, and asset type.
Consider keeping overrides under a different root path (eg: /overrides/marketpath/superbanner/v1).
If one or more javascript and/or stylesheet assets are taken from another source (eg: git, a third party website, etc…) then the original file structure and naming conventions should be used under the relevant root path.
Template, Javascript, and Stylesheet names and paths should not be changed once the package has been activated. This is so that other developers may re-use your assets without fear of a package update breaking their code.
Code standards only apply when working with original code - it is impractical, improper, and unhelpful to backport new code standards over existing third-party code.
Try not to get too fancy with your code unless it is clearly called for - fancy code takes more time, has more bugs, and requires more maintenance than simple code. If you find yourself wanting or needing fancy code, put it into its own package with clear documentation.
Try to use full and descriptive names for functions, mixins, filenames, variables, etc… They make the code easier to read and maintain. Use proper indentation to make logical and visually-distinct groupings of code.
Inside a package - or a group of packages - follow a consistent coding methodology. This means, for example, that if you use BEM-style classnames in one component then you should attempt to apply it everywhere. It also means that you should not mix variable naming schemas if you can avoid it (eg: $primary-color, $orange, $color-theme-background, etc…).
Where possible when writing small quantities of javascript, write vanilla javascript instead of relying on other frameworks. This will make your code more portable and reusable.
Of course, if you are writing a lot of javascript where another framework would be helpful and makes sense then go ahead and use it - but the javascript framework should generally be included in its own separate package and referenced by your package rather than included directly in your package javascript files.
All third-party javascript libraries should include a version number - either in the path or in the filename, while first-party javascript (code that YOU write) may optionally include a version number. The version number typically only needs to include major versions so long as there are no breaking updates (not backwards-compatible) in minor version updates.
Functions and variables should be scoped to a single global object (or a small number of global objects if necessary) with a sufficiently unique name to prevent naming conflicts. It often helps to write code inside an IIFE to prevent global scope pollution.
All javascript assets should end in .js
When copying stylesheets from third-party libraries, use the same type of stylesheet that they originally used (so if they wrote vanilla CSS then you should write CSS too, or if they wrote SCSS your code should be SCSS).
When creating your own stylesheets, use scss or less since those are easier to customize. Furthermore, when you do so, consider breaking up your stylesheets into smaller (partial) stylesheets which may be imported into your main stylesheet.
Mark partial stylesheets as not compiled.
Stylesheets should be careful not to hide visual indicators (such as bullets) in editable content areas. This makes it difficult to edit the actual content. Additionally, changing text to white makes it difficult to see the text in a content area. When it is necessary or desirable to make text white (or light-colored), consider adding a CSS override for body.cke_editable to make the text visible inside the HTML editor.
All stylesheet assets should end in either .css, .less, .scss, or .sass
Templates should be clean, well organized, and labeled in an intuitive manner.
Limit the total number of page templates, each restricted to the specific entity types they should be used with. Ideally each page template should be restricted to a single entity type, since that will make for a better user experience when creating new pages.
Where possible add images to your page templates, which should be representative of what a page created using that template might look like when your package is installed on another site.
Break up your partial templates into individual logically-organized templates for each section of your site. Use “DRY” templates (“Don’t Repeat Yourself”) wherever possible and reasonable.
By creating templates for common “functionality”, you can use them almost like custom reusable functions. Just be sure to document how to use them in a comment at the top of each partial template - including the purpose, “Inputs”, “Outputs” (if applicable), and override/customization options (if applicable).
Template variables should take advantage of {% var %} and {% set %} functionality as much as possible - {% assign %} should only be used where it is strictly necessary, and when used the variable name must be sufficiently unique to avoid naming collisions. Additionally any variables saved on the global scope using the {% assign %} method should be described in the package documentation.
Partial templates that rely on a particular CSS or javascript framework (eg: “bootstrap”) should note it by a comment at the top of the template or some other equally clear method.
All template assets should end in either .html, .liquid, .txt, or another extension that makes sense intuitively for that asset.
For full compatibility with these development guidelines all templates should start with a comment that includes:
All CSS and javascript should be added to the document using the {% add_javascript %} and {% add_stylesheet %} methods. Note that adding the same javascript or stylesheet multiple times is OK since liquid will only output it once in the compiled page. Be sure to clearly document how to customize or disable your javascript and stylesheet files.
When including javascript and stylesheets from templates, you should make every reasonable effort to ensure the following:
Each package should have:
Particularly note any functionality that uses custom (or core) site settings since those values will need to be intentionally reviewed and set after the theme is installed.
Each package needs to be customizable without having to override core package assets (assets set to "install and update"). The documentation should clearly state the ways that the theme may be customized without overriding core assets.
In some cases this may be accomplished by passing in configuration variables to components. In other cases you should use install-only assets, such as template and variable override files. Note that wherever possible default values should be included even if they are not explicitly passed in or overridden. This will make your components more robust in general and will make package updates smoother.
It is not necessary at this time for all packages to be multi-lingual. However, if you desire for a package to be usable on a multi-lingual website then all text should be customizable by language. Some ways to do this:
All packages should make a good-faith effort at outputting "accessible" markup. Before activing a package, consider how screen readers and different users/browsers may interpret the output. There are a number of relatively simple ways to improve the accessibility of your code, including but not limited to:
Packages must not include any assets which you do not have the rights to distribute to anyone with access to your package. This means that public packages cannot include assets that are not free for commercial use. If you have the right to distribute that content (scripts, images, etc…) it must be documented in the code and must follow any other requirements stated by the owner of the intellectual property.
If your package includes content that requires agreement to the terms and conditions, those terms and conditions must be included in the package agreement. However, you should NOT include agreements for child packages in the parent package since users will be required to agree to the child packages at the time that they are installed.
You should not have to include more than one agreement per package - if your package requires agreement to multiple terms and conditions then it should probably be broken down into separate packages with their own agreements.
In particular, you must double-check that you have permission to distribute all images and documents in each package.
Avoid referencing outside JS or other resources where possible. Instead these assets should be served from the Marketpath CMS site.
Examples of files that are ok to use from their original source:
Examples of files that should be copied to the Marketpath CMS site:
Any third-party APIs that require a “key” (or “token”, etc…) should use a custom site setting for that key - with no default value. Otherwise you will end up exposing your key to other developers and bad things will happen!
When building templates, consider how easy it is for a user to create and edit new pages. Field names should be obvious and most fields should have descriptions. Use field conditions and validation where possible. Field values should be easily edited and flow in the same order as their position on the page if possible.
While the main content on each page should be unique, much of the supplemental content on a website may be repeated on multiple pages. Where possible, repeated content (eg: testimonials, projects, featured content, etc...) should be managed in a single location and referenced across the site.
It may be valuable for repeated content to be able to be customized on individual pages while remaining the same on all other pages. In that case, the default option should be to use the "standard/default" values and only provide custom values when the user explicitly overrides the default values.
Examples:
Only set default values on custom fields where the default value would make sense on most websites, since there is a strong probability that the default values will find their way onto live sites. In particular this means that default values should contain no dummy text (Lorem Ipsum or similar) or proprietary intellectual property.
While it may be helpful to a small number of users, you shouldn’t add every conceivable option for every possible scenario. KISS - keep it simple stupid. Too many options add confusion.
The following changes have been made to the Package Development Guidelines:
| Date | Change |
|---|---|
| 01/12/2023 |
|
| 03/14/2023 |
|