Skip to main content

Content Authoring how to

WYSIWYG Guide: Images, PDFs, Tables, Captions, and Video

The Cascade CMS WYSIWYG editor is best when you use it for content authoring, not layout hacking. This guide combines the most common editor tasks into one practical reference: when to insert an image, when to link to a PDF, how to build accessible tables, where captions belong, and what to check when embedded media does not behave the way you expect.

Quick decision guide

Choose the editor action based on the content you are trying to add.
You need to add Best approach Avoid
An image users should read with the page Insert an image asset with alt text and optional caption Uploading decorative screenshots without alt text
A downloadable document Upload the file asset, then create a text link to it Using an image instead of a proper file link
Tabular data Use a real table with headers and, when needed, a caption Using tables for layout or spacing
Video or rich media Use the approved embed workflow or source snippet your site supports Pasting raw third-party embed code without checking site policy

Working with images

Use images when they add meaning, context, or visual explanation to the content. In Cascade CMS, images should be uploaded as file assets first, then inserted through the editor using the Insert/Edit Image button. This opens the Cascade file chooser, which ensures the image path is managed by the CMS and will update automatically if the file is moved or renamed.

  • Upload images to your site's designated image folder (often /_files/images/ or similar) rather than scattering them across the asset tree.
  • Write alt text that explains the image's purpose in context. The alt text field is part of the Insert/Edit Image dialog.
  • If the image is purely decorative, follow your site's guidance for handling decorative images instead of inventing placeholder alt text.
  • Do not paste external image URLs directly into the editor — use the file chooser so Cascade can manage the link.

Tip

If you are adding the same image in multiple places, use the same file asset each time instead of uploading duplicate copies. Cascade tracks relationships, so replacing the original file updates every reference.

Linking PDFs and other documents

Documents should usually be presented as links, not as screenshots or pasted text. Upload the file as a file asset in Cascade first, then select the text you want to use as the link and click Insert/Edit Link. Use the Cascade file chooser to browse to the document — this creates an internal link that Cascade will manage if the file is moved.

  • Use link text like Download the annual report (PDF) instead of vague labels like Click here.
  • If file size matters, include it in the link text or nearby copy.
  • Set the link target (same tab or new tab) based on your site's standards. The Insert/Edit Link dialog includes a Target option for this.

If a document is replacing an older version, upload the new file to the same file asset in Cascade rather than creating a duplicate. This ensures every page that links to that document gets the updated version on the next publish.

Building accessible tables

Tables work well for true row-and-column relationships such as price lists, office hours, and comparison grids. They work poorly for visual layout. If the information can be read as a simple list, a list is usually better.

  • Use the Table Properties dialog in the editor to set header rows or columns. This adds the correct <th> elements and scope attributes so screen readers can understand the structure.
  • Use a caption when the table needs a short label or context sentence.
  • Keep tables narrow enough for mobile layouts when possible.

Common table mistake

Do not use empty cells, merged cells, or manual spacing to force a layout effect. Those shortcuts usually make the table harder to read and harder to maintain.

When to use captions

Captions are helpful when the media needs a short label, credit, or clarification. They are not required for every image or table. Add one when it improves comprehension, not just because a caption field exists.

Good captions usually do one of three things: identify the subject, provide a source or credit, or explain why the media matters in the current article.

Video and embedded media

Video workflows vary more from site to site than images or tables do. In many Cascade CMS implementations, video is handled through a structured data field (such as a YouTube or Vimeo URL field) rather than by pasting embed code directly into the WYSIWYG. The Format then renders the embed markup on publish. Other implementations may use a dedicated Block or a content type field for video.

Before embedding, confirm:

  • Which video provider is approved for your site (YouTube, Vimeo, Kaltura, etc.).
  • Whether the video URL belongs in a structured data field on the page or directly in the WYSIWYG editor.
  • Whether transcripts, captions, or fallback links are required for accessibility compliance.

Real-world example

A content author is building an event page for an annual conference. The page needs a banner image, a downloadable agenda PDF, a pricing table, and a highlight reel from last year. The clean implementation is:

  1. Insert the approved banner image with meaningful alt text.
  2. Upload the agenda as a file asset and link it with text such as Download the conference agenda (PDF).
  3. Create a proper pricing table with header cells for attendee type and rate.
  4. Add the approved video embed method or component instead of pasting arbitrary third-party code into the editor.

This produces content that is easier to maintain, more accessible, and less likely to break when the site theme changes.

Common mistakes

  • Pasting styled content from Word or another site and keeping the imported formatting. Use Paste as Plain Text or the paste cleanup options in the editor to strip unwanted styles.
  • Using an uploaded screenshot of a document instead of linking the actual PDF.
  • Adding tables for spacing rather than for data relationships.
  • Forgetting alt text or reusing the file name (like IMG_2847.jpg) as alt text.
  • Pasting external URLs for images or documents instead of using the Cascade file chooser to create managed internal links.
  • Assuming missing toolbar options are broken when they may be intentionally restricted by the WYSIWYG editor configuration set by your administrator.

If the editor strips your markup

That is usually a configuration or filtering decision, not random behavior. If a class, embed, or attribute keeps disappearing after save, check with your administrator before trying to work around the editor manually.