Apostrophe Styleguide

ApostropheCMS Website

Assets management

Scss

For global style like colors, utilities, etc. everything is in lib/modules/theme/sass imported in the site.scss file.

For module specific styles, the scss files are placed next to the concerned templates. In this folder lib/modules/table-widgets/views there are two files: widget.html and _widget.scss.

JS

There isn't a lot of client side javascript, the behavior is similar to scss files. All client side JS that has nothing to do with Apostrophe (nothing related to admin, so for final user) is imported inside lib/modules/theme/js/site.js and used as an entry point by webpack.

SVGs

  • When your svg files are in lib/modules/theme/images:

You can access them independently with their path:

{{ svg.render({ image: '/lib/modules/theme/images/apostrophe.svg' }) }}
  • When your svg files are in lib/modules/theme/images/sprite:

Webpack transpile them into a single sprite file.

You can access them using the same macro with a different param: icon

{{ svg.render({ icon: 'caret-down' }) }}

And you just have to pass the name of the svg (file name).

Helpers

In this folder lib/helpers, there are mainly functions to get Apostrophe schema parts.

If you don't find in the project what you're looking for, have a look at the apostrophe-common project. We started getting rid of it during the migration, since this repository is only used for old project, and maybe even only for the website..

Warning: don't break our sitemap / SEO

  • If a piece type has no show pages, you should make sure it is excluded from the apostrophe-site-map configuration. See app.js for where this configuration is currently passed.
  • If a piece type DOES have show pages, you should make sure it is NOT EXCLUDED from the apostrophe-site-map configuration. We missed this with extensions because back in the day, they didn't have show pages, but now they do.
  • Please keep this in mind especially when adding show pages where they formerly did not exist.
  • Also, if you wind up implementing special routes or custom pieces-pages dispatch routes that render webpages, you will need to use the existing support for passing additional URLs via a custom function in apostrophe-site-map. Otherwise they will not be discovered by the sitemap module. Tom is a good person to consult. You don't need to worry about this if you're just creating ordinary page types, or ordinary pieces-pages types with show.html and index.html and no other custom dispatch routes.
  • For SEO reasons, please make sure headings are actual heading tags. See existing logic that uses a special apos.areas.headingText helper to help with this.

Customizing robots.txt

See staging-robots.txt and prod-robots.txt. The appropriate file is automatically copied to robots.txt during deployment by a custom script in package.json. Please populate them appropriately for each environment. Please do not create a new robots.txt directly in the repo.

A3/A4 Migration Status

A migration to A3 was attempted and then suspended after considerable progress quite some time ago.

The work was done in another repository. Be aware that a great deal of change has occurred in this repository since then.

So no change should be done in the current project about A2 to A3 migration.

There is a tool to help migrate code and data migrations that has been used.

From what we remember, it has been stopped when arriving at the webpack upgrade step. The code upgrade was be almost finished, but would need extensive reconsideration due to changes in this repo since then.

The webpack config should be, in part, removed (for scss files for example since A3 handles that pretty well, same for client side javascript),

ut for svg, it should be looked at more carefully to see if we want to keep the sprite generation or not.

Lastly, for Apostrophe specific client side javascript (always.js, user.js files), it should also be looked at more carefully to migrate this code if needed following A3 best practices.

Since the project already uses a sprite and individual svg, we should choose one way and the easiest one (no sprite could allow getting rid of the webpack config associated).