Inserting links to Contentful-hosted PDFs

I’m trying out Contentful for a work project.

In the Markdown editor, I can insert an arbitrary absolute link using the chain link icon. I can alternatively use the “Insert media” button, but this seems intended for inserting images only (despite the “Insert existing assets” dialog showing non-image assets).

My question: how should I train my non-technical users to insert a link to a PDF that Contentful hosts?

It seems error-prone to expect non-technical users to use “Insert media” to find the URL of a hosted PDF, then munge the inserted Markdown into a standard Markdown link.

(I was expecting a UX similar to Wordpress: clicking the chain link icon would let me add an arbitrary URL or search for existing assets.)



Hello! :wave:

You are able to click on Insert media and select a PDF that will be inserted into the Markdown editor in the image link format. If this isn’t working as expected for you, can you please tell me what are the steps you are taking in order to upload and insert a PDF file?

Thanks for the reply.

Let me try to explain more clearly.

The people creating and editing content will mostly be non-technical users. They won’t be Markdown experts. They want to be able to write text that links to a PDF hosted by Contentful. For example, text like “Please read the white paper about this technology”, where the text read the white paper is a standard hypertext link to the PDF.

As far as I can tell, these are the steps a user needs to take to do this:

  1. Click “Insert media”, then select “Link existing media”.
  2. In the dialog, search for the PDF and click OK.
  3. Edit the resulting Markdown syntax to change it from image syntax to standard link syntax, and merge it into the text where they want the link.

The user experience here is poor. For technical people who know Markdown, it’s irritating. For non-technical people, it’s confusing and error-prone.


Problem 1: going against user expectations

A user wants to insert a link, so they will press the chain-link icon in the toolbar. That’s how you insert links: they’re familiar with this button from many other applications. Pressing the chain-link icon brings up the “Insert link” dialog, but this dialog doesn’t let the user search for assets like PDFs. To insert a link using this dialog, the user must know the URL in advance.

After the user presses the chain-link icon, and realises they don’t know the URL to the PDF, what will they do? They might go to the Media section of the Contentful site, search for the PDF there, display the edit page for the PDF asset, and look for the URL. As far as I can tell, the URL is not shown on that page.

What the user “should have done” is press “Insert media” instead of “Add link”, even though they wanted to add a link, not insert media. This is likely to cause frustration.

Problem 2: expecting a user to understand Markdown syntax to recover from problem 1

OK, the user has discovered they can find the URL for a PDF using “Insert media”. This adds Markdown to the content. The Markdown syntax is for an image, not a simple hypertext link. These two syntaxes are very similar, but not the same.

The user now needs to edit this inserted Markdown to turn it into a standard link, update the link anchor text, and put the link in the right place in the content. Not difficult, but easy to get wrong, especially if the syntax is unfamiliar. If they accidentally remove a square bracket or parenthesis, it breaks. If they accidentally retain the exclamation mark, it’s not going to work.

Being forced to do this because of problem 1 increases the likelihood of errors, as the user is already frustrated.


  • Additional training, as problem 1 means user expectations are not met.

    In concrete terms: I’m going to have to stand in front of people and say: “To add a link to a PDF, DO NOT use the ‘add link’ button. Instead, use the ‘insert media’ button, even though you don’t want to insert media, and even though it doesn’t make sense to try to display a PDF as an image anyway. Then remove the exclamation mark from the inserted Markdown, edit the text in square brackets, and copy and paste the entire thing where you want it.”

  • Additional support, as problem 2 results in content with broken or unexpected Markdown syntax.


Let users search for assets in the chain-link button’s “Insert link” dialog. Both problems go away.

I hope that makes sense.



I completely understand your concerns.

We do have a rich-text editor UI extension for which I had hoped would solve your concerns; however, I tested it out and it doesn’t handle PDFs.

Our current editor is based off of CodeMirror.

My recommendation is to train your non-technical editors to consider PDFs as “media” files in the world of Contentful (as you have already surmised). That way, they can insert PDF files directly from the Insert media button in our Markdown editor without having to learn the Markdown syntax for linked files.

I think the trick in having your editors start thinking of linking PDF files as media instead of inserting links is:

  • Inserting links means you want to hyperlink a string of text.
  • Inserting media files means adding/“linking” an existing media file (media could mean images, videos, PDFs…).

Yes, this is slightly different than how Wordpress presents their UI and I can definitely see the case for expanding the Insert link functionality of the current editor. I am not sure what the scope of that project would be but I will bring this feedback to the product team.

In the meantime, I’d like to give a plug to Markdown. :grinning: While it looks “technical,” it is extremely human readable and is the simplest way to add very basic styles to your content without knowing any code. It reduces the error for copying over incompatible/secret styles from other content editors (such as email) and allows writers to focus purely on their content without worrying about how the content will be displayed to the end user (the developers will handle that). There are tons of great cheatsheets online such as this one.

Our current editor can expand into a side-by-side editor where the user can write MD while also previewing what the styles will look like to the end user (if you have a Markdown parser installed in your web project)–just click on the expand button in the editor to access this functionality. Last thing, if the user gets stuck, we’ve also linked a cheatsheet at the bottom of the editor.

Good luck with your training and thanks for your feedback–we are constantly considering ways in which we could improve the non-technical editor experience.

1 Like

Thanks. I’ll see if I can find a way of explaining things that works.

As you’re talking to the product team, I’d like to make a related suggestion: allow users to enter site-relative URLs in the “insert link” dialog.

Currently, the “insert link” dialog requires users to enter absolute URLs: for example, "" But if a user wants to link to another page on the same site, it’s more sensible to use a site-relative URL: for example, “/some/path”. Site-relative URLs are important in the case of staging sites: development, preview, live, and so on. Each of these sites is typically served by a different domain. With absolute URLs, editors checking a preview server might “silently” navigate from the preview server to the live server when clicking a link. Using a site-relative URL means the domain would not change.

To insert site-relative URLs at the moment, users must either use the “insert link” dialog to enter an absolute URL and then edit the Markdown to remove the protocol/domain prefix, or insert the link Markdown manually. Neither approach is ideal.

Thanks again.


Great ideas! Will add this to my product ticket. Thanks!

So I’ve been experiencing a problem with this very issue:

  • Using the Markdown editor I uploaded a PDF via the “Insert media” option of the Markdown editor. It duly converts that to markdown however in the rendering the Contentful API outputs an <img tag rather than a hyperlink or object tag and thus it renders as a broken link. Even in the preview tab of the Markdown editor it renders as a broken link

The same happens for uploaded rich media e.g. video etc

Anybody else experiencing this issue?

I also see this behavior. The “Insert Media” button’s primary purpose is inserting images from your Contentful media library into the markdown text. Currently, it is only treating media as images and isn’t checking to see if the linked media is an image (which it should insert with an <img> tag) or something else (which it maybe should insert with an <a></a> tag).

The markdown it inserts looks like

![a file](//

and that is standard markdown that is rendered into an <img> html tag like this:

<img src="//" alt="a file">

If you change the markdown just a bit by removing the initial exclamation point ( ! ) at the beginning so it looks like this:

[a file](//

then it’ll get rendered into an <a></a> tag like this:

<a href="//">a file</a>

Let us know what you think of this but know that I’ve submitted this feedback to our product team so hopefully this can get improved soon!

tl;dr remove the initial exclamation point ( ! ) from the markdown added by the “Insert Media” button to get a link instead of an image.

I think the problems and recommendations I posted about several months ago, at the top of the thread, are still current. I hope Contentful can address these.

Is it absolutely necessary to have the links to the PDF files inside the Markdown field? How about adding a field “Attachments” that is a relation to multiple media assets. This way the content producer doesn’t have to worry about broken static links.

Hello @avaragado,

I am a product manager at Contentful, responsible for the Authoring experience, so your feedback in this thread is relevant to our line of work.

In fact, it is relevant with a feature we’re currently working on, which is a new (rich) text field that we currently have available in a closed Alpha. The issues you’re pointing out:

  • Hyperlinking to an asset (whether it’s an image or a pdf file)
  • Linking to relative URLs
  • Or linking directly to entries

will be addressed by this feature. Its current state doesn’t have this linking functionality (it only supports basic formatting for now) but if you want to get acquainted with its underlying schema as a developer you can already use it in a test space.
The above features are to be built in the next months.

I have created a topic in the Announcements where you can see how to participate in this program: Structured Text field type Alpha

Thank you and let me know if you have any questions.

Raising an old topic, our company has a huge need for something simple to browse and link to PDF and other documents. In addition to the shortcomings listed with inserting links to PDF assets, there is a UI problem wherein we cannot read the full title of the asset in the dialogue browser.

Is there a way to adapt the UI for the asset browser? I have multiple files with similar file names rendered as thumbnail images with the title cut off before you can read in full.

Also ability to insert more than one at a time would be huge help

Many thanks

Hi @peter.jones! Welcome!

The question about the asset UI/UX you raise would be best answered if you created a new topic and included more details and screenshots to fully describe what you mean.


I am having this same issue.
I can’t migrate my clients from wordpress as they publishing links to PDFs all the time.
All the insert media does is add a broken image… which will give poor SEO also.

Any @contentfuladmin still looking into solving this?
A new option inside the ‘insert media’ option would be good - simple a toggle between “Image or Link only”