Use processing directives to control document output

​

Introduction

Even though Cloudpress does a great job of converting the content of your documents to the correct format of your Content Management System (CMS), it is not always possible to create the desired output in Google Docs and Notion.

The reason for this is that there is a disparity between your Google Docs/Notion and your CMS. You CMS has certain features for which there is no equivalent in Google Docs or Notion.

For example, your CMS may allow you to layout images in a certain way. Or you may be using WordPress and want to insert a custom Gutenberg block in your content.

In cases like this, you can use processing directives.

​

How processing directives work

A processing directive is a special bit of text you can insert in your document that will instuct Cloudpress to behave in a certain way when converting and exporting your content. It may instruct Cloudpress to interpret content in a certain way. Or it may instuct Cloudpress to export the content in a specific way.

1. A processing directive always starts with the characters @@, followed by the directive name.
2. It may also contain a list of arguments inside parenthesis ().
3. The arguments must be in the format name=value.
4. If the value contains spaces, it must be surrounded by quotes ("), e.g. name="Some value".

The following are examples of processing directives:

@@image

@@image()

@@image(filename="the-african-wild-dog")

@@image(alt="An African Wild Dog in the Kruger National Park", caption="An African Wild Dog in the Kruger National Park in South Africa")

The line containing the directive must not contain any other text before or after the directive. For example, the following is invalid:

This will not work @@image(filename="the-african-wild-dog")

​

Processing directives supported by Cloudpress

Cloudpress currently supports the following processing directives:

​

@@image

The @@image directive allows to to specify extra information for an image, such as the alt text or caption. The @@image directive applies to the next image that Cloudpress encounters in the document.

The @@image directive supports the arguments listed below:

Below are a few examples using the directive:

• @@image(filename="the-african-wild-dog"): Specifies that the filename for the next image must be “the-african-wild-dog”
• @@image(filename="the-african-wild-dog", alt="African wild dog in the Kruger"): Specifies that the filename for the next image must be “the-african-wild-dog” and the alt text must be “African wild dog in the Kruger”

​

Important things to note

• Attributes specified with the @@image directive will override the values from the image in the document. For example, if the image in the document has an alt text specified, and you also specify the @@image directive with an alt attribute, Cloudpress uses the alt attribute from the directive rather than the alt text from the image.
• All attributes are optional. However, if you specify an @@image directive without any attributes, it will have no effect.
• Not all attributes are supported by all CMSs. Please review the CMS image text support table for more information.

​

@@begin_raw_content and @@end_raw_content

The @@begin_raw_content and @@end_raw_content directives are used in a pair to denote the start and end of a raw content block. All the content between @@begin_raw_content and @@end_raw_content are exported to your CMS as-is. This allows you to export content to your CMS which would not otherwise be supported by Cloudpress.

Since Cloudpress exports the content as-is, Cloudpress will only export the types of content contained between the @@begin_raw_content and @@end_raw_content as per the table below. Any other type of content will be discarded by Cloudpress.

In all cases, Cloudpress will drop any formatting from the text. In other words, if your text contains formatting like bold or italics, Cloudpress will remove it during the export.

​

@@begin_code_block and @@end_code_block

The @@begin_code_block and @@end_code_block directives are used in a pair to denote the start and end of a code block.

These directives are supported only in Google Docs and must contain only normal text between the @@start_ and @@end_ directives. Any other type of content will be discarded by Cloudpress and any formatting (like bold and italics) will be removed from the text.

The @@begin_code_block directive supports the arguments listed below:

The screenshot below shows a sample code block in a Google Doc.

When exported to, for example, WordPress, this is converted into the correct Gutenberg block.

​

@@split

The @@split directive is used to split the content of your document across multiple fields in your CMS. This is useful when you have multiple rich text fields in your CMS that you want to update from a single source document.

You can use multiple @@split directives in a single document with each instance of the @@split directive splitting the content to a separate field.

The @@split directive support the arguments listed below.

This fieldname argument will depend on which CMS you use. Please refer to the following Cloudpress documentation for the various CMSs.

• Set additional field values in WordPress
• Set additional field values in Contentful
• Set additional field values in Webflow
• Set additional field values in Sanity
• Set additional field values in Kontent.ai