Include ability to caption post heros for blog theme

[finleyjb]

According to Unsplash's API Guidelines, uses of its images must link back to the photographer and attribute unsplash. It would be nice if the blog theme allowed me to attach some sort of frontmatter that allowed me to add a caption to have this attribution.

[laurieontech]

Would certainly be open to a community contribution adding this!

[eliasm307]

Hello @laurieontech i would be up for giving this a go, if it's still available.

From my understanding I think there are at least 3 ways to do this, explained below. Would you be able to let me know if I'm on the right track and which solution is preferable? This is one of my first contributions to open source so any advice you have would be appreciated.

For the options below I prefer either option 2 or 3, and just need to know which of these is preferable or if there is a better option before doing too much work on it.

1. Add a frontmatter field to enter the caption as HTML directly which is then rendered directly using React __dangerouslySetInnerHTML (my least preferred option)

Advantages: caption can be customised by user

Disadvantages: malicious is code could be used for the caption; external tool might be required to sanitise HTML

2. Add a frontmatter field to enter the caption as markdown which is then rendered as HTML

• Advantages: caption can be customised by user; seems as if rendering markdown in frontmatter might be supported in Gatsby via the MDX renderer however I would need to look into it (https://www.google.com/url?sa=t&source=web&rct=j&url=https://github.com/ChristopherBiscardi/gatsby-mdx/issues/352&ved=2ahUKEwj9taXLmdbtAhUF1hoKHQ4PDOoQFjAAegQIARAB&usg=AOvVaw04Y8i0U5Toeo9ZVAZMPPns&cshid=1608252354678)

• disadvantages: Markdown is still susceptible to malicious code (https://medium.com/taptuit/exploiting-xss-via-markdown-72a61e774bf8) so an external sanitisation library might still be required if not already included with the MDX renderer method

3. Adding a caption field in frontmatter that is actually an object with various properties such as authorName, sourceName, and relevant links, then using the values of these fields to conditionally construct the caption text

• Advantages: requires no external tools, safer?, a bit more straightforward to use for non technical users

• disadvantages: caption format is fixed which means it might not be suitable in some cases e.g. i18n where the caption template is fixed to one language

I look forward to hearing from you.

[laurieontech]

@eliasm307 thanks so much for picking this up. I’d opt for option 2. This theme is already designed for use with MDX so you should be able to add it to the frontmatter. However, you don’t need to support anything other than plaintext.

What I would recommend is making a separate caption component so that people can shadow it and make changes as they see fit. Then conditionally displaying that should a caption be available for the given hero.

[finleyjb]

I suppose the caption wouldn't need to support arbitrary HTML or markdown, but it seems like it should at least offer a way to link back to the unsplash/pixaby page or whatever the platform requires you to link to.

[eliasm307]

Hello @laurieontech thank you for your feedback. Making a caption component sounds good.

However I didn't quite understand what you meant by people will be able to "shadow" the component, would you be able to clarify please? My understanding of what you said is that there would be a caption component that would take the caption text as props then the component could be modified as required to style the caption. Is the user modification what you meant by "shadowing"?

Also, regarding your statement about only needing to support plain text, I just want to clarify how this would meet the requirements where there is only one caption field in the markdown. From the link @finjo-the-great included in the issue, the requirement from unsplash is for a caption explicitly with a link to the author's Unsplash profile, an example format is given below:

Photo by Annie Spratt on Unsplash

Apologies but I don't see how something like the above could be generated from a plain text string. I'm taking plain text to mean without any html or markdown so no capability to add hyperlinks. I would assume atleast the caption text and the link to the author would be required, unless if I'm misunderstanding something?

[eliasm307]

How about using 2 fields for the caption, one which would be the caption text, then an optional one for a link which would make the whole caption a hyperlink?

[laurieontech]

Apologies for the delay here, we were off for the holidays.

I hadn't considered the link piece. I think creating a format with specific fields is reasonable. To handle internationalization there should be no English text included. Perhaps something like:
<startCaptionText> <linkName><link> <endCaptionText>.

It only allows for a single link, but it's very configurable.

[eliasm307]

@laurieontech thanks for your reply, hope you had a good break.

I'll look into implementing the solution you described when I get a moment however, I had looked around and found the following in the gatsby contribution guides here

Its a solution for a similar problem however I couldnt find the code for the components with the implementation.

[laurieontech]

Ah, this is the old site code for authoring blog posts. We've since moved to a CMS so I'd have to go digging in git history. But as a pattern it's a perfectly reasonable one to duplicate.

[eliasm307]

@laurieontech I've created a pull request using two frontmatter properties for the caption text and caption link. This was easier and also I think it is more straightforward and flexible to use as the text can be however the user wants using just one markdown field, however, the whole thing becomes a hyperlink if a caption link has been defined, but I don't know if this is actually an issue?

If you strongly prefer the format you had suggested ie , I can work on that but I feel this would be a bit confusing on the markdown side as you need to understand the context of the fields to know the order to fill in fields so the resulting caption comes out in the required order.

Either way, I look forward to your feedback

[LekoArts]

Implemented with #95