Static Publishing Best Practices
Note: Static Endpoints are only supported in dotCMS Enterprise editions for customers with a Site License (Platform level license). Please see the list of dotCMS versions for more information on features supported in different version of dotCMS.
Prepare Your Content for Static Publishing
In addition to proper configuration, effective static publishing also relies on proper implementation of your dotCMS content to ensure your data can be copied properly to the Static Endpoint and displayed properly by the Static Endpoint's website hosting service. To maximize your site usability and functionality when pushed to a Static Endpoint, please review and implement the following guidelines.
- Do not rely on URL parameters to access content
- Always end image paths with the filename at the end
- End image and page links with appropriate trailing slashes (/)
- Do not use a URL Map pattern that matches the path of a Page URL
Common content accessed by your pages needs to be accessible from the static version of your site. When using Dynamic Endpoints, you can share content within your dotCMS architecture; however when using static sites, the only content available to the static web server is the static content on your site, and content which you link to using publicly accessible URIs.
To ensure the static version of your site has access to common content, reference the content in publicly accessible CDNs where possible.
Do not rely on URL parameters to access content
Simple web servers do not understand or process URL parameters (e.g.
If you wish to use arguments to display the pages on your Dynamic Endpoints, place the arguments in the URI path (or via a URL Map if appropriate) instead of using URL parameters. When the content is then pushed to a Static Endpoint, dotCMS will automatically break the content out into separate folders and content based on the URI path.
Always end image paths with the filename at the end
The dotCMS RESTful image API allows you to perform image processing by appending filters and filter parameters at the end of the image URL, for example:
However if you plan to push your content to a Static Endpoint, this will cause problems as the file “name” as seen by the static web server is “125” (with no image extension).
To prevent problems with Static Endpoints, you should always end RESTful image API links with a file name, e.g.:
This displays the same way on a Dynamic Endpoint, but ensures that the image will also display properly on a Static Endpoint.
End image and page links with appropriate trailing slashes (/)
When you display content on a dotCMS Dynamic Endpoint, dotCMS automatically resolves links to pages or folders whether or not they have a trailing slash (e.g.
However when you push your content to a Static Endpoint, the simple HTML server expects folders to end with a slash and pages to end without a slash. To ensure your content will push properly to a Static Endpoint:
- Make sure all your folder links end appropriately with a slash, e.g.:
- Make sure your none of your page links end with a slash, e.g.:
Do not use a URL Map pattern that matches the path of a Page URL
The URL Map Pattern for each Content Type must be unique within the system, and the root of the URL Map pattern should not match the URL of any Page.
For example, if you have a page with a URL of
/news, it resolves as a Page URL, for example:
You cannot then also have a URL Map pattern that begins with
/news, since that resolves
/news as a folder URL, for example:
When you publish your site to a Static Endpoint, each URL Mapped content item is published as a separate Page within an actual
/news folder, so the simple web server sees
/news as a Folder instead of a Page and the
/news Page is not served properly.
Use Force Push after Changing Common Elements
When you change common Page elements such as Containers and Templates or page headers and footers, these elements individually are pushed to Dynamic Endpoints, and because the Dynamic Endpoint automatically pulls the latest version of these elements, all pages on the Dynamic Endpoint automatically display the changes.
However when you push Pages to a Static Endpoint,
Because of this, it is recommended that when you push content to a Static Endpoint, you use the Force Push option more frequently than when you push to a Dynamic Endpoint. Specifically, after changing any shared elements, it is recommended that you Force Push the entire site to the Static Endpoint, to ensure that all Pages and other content that depends on the shared elements will be updated properly.
Shared Elements which may require a Force Push of the site to the Static Endpoint include:
- Content Types
- Content displayed in multiple Pages
- Individual content items
- Navigation, including:
- Menu Links
- Folders or Pages with
Show on Menuset
- Categories, Tags, or Relationships if they are used to generate navigation
- Page Elements
- Themes (headers, footers, styling, etc.)
- Permissions (such as when adding or removing Permissions for the CMS Anonymous Role)
- Recurring Events
- Specifically site properties referenced in page headers or client-side code, such as metadata, developer keys, etc.