Accelerated Mobile Pages Module (AMP Filter) is a custom module for Kentico CMS and EMS. It consists of an Output Filter for transforming regular HTML to AMP HTML format and a macro method that makes it easy to adjust and fine-tune the rendered output. The project is based on a master thesis (EN) of Daniel Minarik (full text).
💡 Read how we implemented AMP on Kentico Advantage website.
- Install the NuGet package
Kentico.AcceleratedMobilePages
To enable AMP Filter on a site:
- Go to Settings -> System -> Output filter -> AMP Filter
- Check that "Enable AMP Filter" is on
- Set an AMP domain name (e.g.:
amp.domain.tld
if the web is hosted on www.domain.tld). - Go to Sites -> Edit site -> Domain aliases
- Create a new domain alias corresponding with AMP domain name specified earlier
There are two options for how to activate an AMP Filter for a specific page:
-
In Accelerated Mobile Pages application, add pages by selecting them from the site content tree.
-
In Pages application, by selecting a particular page from the content tree, navigating to Properties -> AMP Filter, and then selecting "Enable AMP for this page".
There are several ways of including cascading style sheets into an AMP page:
-
Set a default CSS stylesheet for the whole site (in Settings -> System -> Output filter -> AMP Filter).
-
Set a CSS stylesheet for every AMP page separately (Pages -> Edit -> Properties -> AMP Filter -> uncheck "Use default stylesheet" and select the desired stylesheet)
-
If none of the previous options is set, the AMP Filter will use the regular CSS stylesheet assigned to the page (either the site's default stylesheet or the page-specifc one). This option is not recommended, as the stylesheet could be bigger than 50kB (e.g., if it contains styles for the whole website).
The AMP standard offers a lot of components or tags which do not have an ordinary HTML equivalent, and therefore, they can't be automatically injected or replaced in the page's source code.
You can use the {% AmpFilter.IsAmpPage() %}
macro to find out whether the AMP Filter is enabled and active on the current page. This is useful for showing and hiding different parts of a web page. To do that, use the macro as a visibility condition of a web part.
Some advanced components, such as social media embed, advertisement, analytics, video or audio require a script to be included in the head element. To do that, use the Head HTML Code web part.
For pages that have the AMP Filter enabled:
-
If the page is accessed from a non-AMP domain:
- AMP Filter will insert an
amphtml
link to the head tag of the page (this allows discovery of AMP-enabled pages)
- AMP Filter will insert an
-
If the page is accessed from an AMP domain, the AMP Filter:
- Removes restricted elements, attributes and their values
- Replaces regular tags with their AMP HTML equivalents (these 5 tags: img, video, audio, iframe, form)
- Inserts compulsory AMP markup required by the AMP standard (such as the AMP runtime script, boilerplate code…)
- Injects a stylesheet as described above
This transformation is done via the HtmlAgilityPack library. It creates a DOM structure and the AMP Filter removes and replaces the elements according to the AMP HTML specification.
Some advanced replacements (which were not possible to implement using the HtmlAgilityPack) are done by regular expressions.
The AMP Filter does not transform cascading stylesheets in any way. The developer must ensure that the stylesheet complies with AMP HTML specification - stylesheet restrictions.
AMP Filter has two types of global settings:
- Font providers settings - a white-list of font providers of custom fonts available for usage via the
<link>
tag. (Other fonts can be used via the@font-face
CSS rule.) - Script URL settings for five different AMP HTML elements. This allows loading of specific (or latest) versions of the runtime scripts.
Both types of settings depend directly on the AMP HTML specification and should be changed only according to the AMP specification.
Even when using the AMP Filter there are still some things that need to be handled by the developer:
- Write valid CSSs according to the AMP specification.
- Follow the AMP specification when using SVG tags (AMP Filter does not affect SVG tags at all).
- Use only white-listed font providers via
<link>
tag or use other fonts using@font-face
CSS rule. - Explicitly state the size for every image (height and width attribute).
- In case of sites with complex styling, the stylesheets need to be reduced so that they do not exceed 50kB in total.
- If a page contains scripts, on-line forms, social media embeds, advertisements, or other interactive elements, the elements need to be replaced with AMP extended components.
-
For simple sites with CSS totalling no more than 50kB in size (and adhering to the official AMP rules), there's no need to create AMP-specific stylesheets - the sites will work correctly with the regular stylesheets.
-
The AMP filter is mainly intened for simple, static pages, i.e. pages containing regular HTML. Only the
<img>
,<video>
,<audio>
, and<iframe>
interactive elements (adhering to the AMP HTML Specification) are allowed. Pages that fulfill these requirements will be transformed into the AMP format. -
The static
<form>
element used by ASP.NET web forms to store metadata and viewstate information is also converted to the AMP format. However, standard<form>
elements included in the page's markup will not be submitted and processed by the server at all. To implement standard on-line form functionality (via the<form>
tag), refer to the amp-form section of the official AMP documentation.
-
Read the contribution guidelines
-
Enable the continuous integration module
-
Remove
<ObjectType>cms.settingskey</ObjectType>
from theCMS\App_Data\CIRepository\repository.config
-
Serialize all objects to disk
-
Open a command prompt
-
Navigate to the root of the project (where the .sln file is)
-
Fork this repo
-
Init a git repo and fetch the web part
git init git remote add origin https://github.com/OWNER/kentico-amp.git git fetch git checkout origin/master -ft
-
Restore DB data
Kentico\CMS\bin\ContinuousIntegration.exe -r
-
Open the web project in Visual Studio
-
Add
Kentico.AcceleratedMobilePages\Kentico.AcceleratedMobilePages.csproj
to the solution -
Add
Kentico.AcceleratedMobilePages.Publisher\Kentico.AcceleratedMobilePages.Publisher.csproj
to the solution -
Add reference from CMSApp to Kentico.AcceleratedMobilePages.csproj
-
Add reference from CMSApp to Kentico.AcceleratedMobilePages.Publisher.csproj
-
Build the solution
-
Optional: Assign the module to one or more sites
-
Make changes
-
Use combination of
git add
,git commit
andgit push
to transfer your changes to GitHubgit status git commit -a -m "Fix XY" git push
-
Submit a pull request
Tested with Kentico 11.0 (net46).