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.

Ensure the URLs in all HTML tags are relative

When you static publish content, dotCMS does not rewrite any of the URLs in your content. This means that, for any links in your content to work as a static site, the links must be relative to the path where you are publishing your static site.

• Links which reference a specific Site on your dotCMS instance will not work.
  • Example: Links in the form //site.name.com/applications/themes/images/image01.jpg will not work with Static Publishing.
• If you configure your Static Publishing Endpoint to publish all pages to the root of the target site, you can use links which are relative to the root of your site.
  • Example: /applications/themes/images/image01.jpg.
• If you configure your Endpoint to publish content to a subfolder of the target site (using the aws_bucket_folder_prefix property), then the links must be relative to the Page where the link is located.
  • Example:
    • If you have a Page located at /contact-us/our-team folder on your site.
    • Links to the above image would need to be in the form ../../application/themes/our-theme/images/image01.jpg

Use Content Delivery Networks (CDNs) for common libraries, JavaScript libraries, and fonts

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. ?param=value).

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:

http://demo.dotcms.com/contentAsset/resize-image/5d021a67-dafa-4244-be12-a3afdc956dd6/image/h/125
http://demo.dotcms.com/dA/5d021a67-dafa-4244-be12-a3afdc956dd6/filter/Resize/resize_h/125

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.:

http://demo.dotcms.com/contentAsset/resize-image/5d021a67-dafa-4244-be12-a3afdc956dd6/image/h/125/pie-chart.png

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. http://your.domain.com/index/).

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.:

  http://demo.dotcms.com/company/

• Make sure your none of your page links end with a slash, e.g.:

  http://demo.dotcms.com/company/about-us

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:

http://demo.dotcms.com/news

You cannot then also have a URL Map pattern that begins with /news, since that resolves /news as a folder URL, for example:

http://demo.dotcms.com/news/this-is-an-article
http://demo.dotcms.com/news/this-is-another-article

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
  • Widgets
• Navigation, including:
  • Menu Links
  • Folders or Pages with Show on Menu set
  • Categories, Tags, or Relationships if they are used to generate navigation
• Page Elements
  • Containers
  • Templates
  • Themes (headers, footers, styling, etc.)
• Permissions (such as when adding or removing Permissions for the CMS Anonymous Role)
• Recurring Events
• Sites
  • Specifically site properties referenced in page headers or client-side code, such as metadata, developer keys, etc.

Do not use Vanity URLS

Vanity URLS do not work on static websites. A possible work around is to create multiple pages on your dotCMS site; those pages could include the entire contents of another page. This method should only be used on a static site since vanity URLS can be used on a dynamic site.