Skip to content

Commit

Permalink
feat(gatsby-remark-images): Add markdownCaptions option (#16574)
Browse files Browse the repository at this point in the history
  • Loading branch information
@mathieudutour @sidharthachatterjee
mathieudutour authored and sidharthachatterjee committed Aug 13, 2019
1 parent 20fdba9 commit a72cbaf
Show file tree
Hide file tree
Showing 7 changed files with 177 additions and 27 deletions.
1 change: 1 addition & 0 deletions packages/gatsby-remark-images/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ plugins: [
| `maxWidth` | `650` | The `maxWidth` in pixels of the div where the markdown will be displayed. This value is used when deciding what the width of the various responsive thumbnails should be. |
| `linkImagesToOriginal` | `true` | Add a link to each image to the original image. Sometimes people want to see a full-sized version of an image e.g. to see extra detail on a part of the image and this is a convenient and common pattern for enabling this. Set this option to false to disable this behavior. |
| `showCaptions` | `false` | Add a caption to each image with the contents of the title attribute, when this is not empty. If the title attribute is empty but the alt attribute is not, it will be used instead. Set this option to true to enable this behavior. You can also pass an array instead to specify which value should be used for the caption — for example, passing `['alt', 'title']` would use the alt attribute first, and then the title. When this is set to `true` it is the same as passing `['title', 'alt']`. If you just want to use the title (and omit captions for images that have alt attributes but no title), pass `['title']`. |
| `markdownCaptions` | `false` | Parse the caption as markdown instead of raw text. Ignored if `showCaptions` is `false`. |
| `sizeByPixelDensity` | `false` | Analyze images' pixel density to make decisions about target image size. This is what GitHub is doing when embedding images in tickets. This is a useful setting for documentation pages with a lot of screenshots. It can have unintended side effects on high pixel density artworks.<br /><br />Example: A screenshot made on a retina screen with a resolution of 144 (e.g. Macbook) and a width of 100px, will be rendered at 50px. |
| `wrapperStyle` | | Add custom styles to the div wrapping the responsive images. Use the syntax for the style attribute e.g. `margin-bottom:10px; background: red;` or a function returning a style string which receives the information about the image you can use to dynamically set styles based on the aspectRatio for example. |
| `backgroundColor` | `white` | Set the background color of the image to match the background image of your design. |
Expand Down
4 changes: 3 additions & 1 deletion packages/gatsby-remark-images/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@
"@babel/cli": "^7.0.0",
"@babel/core": "^7.0.0",
"babel-preset-gatsby-package": "^0.2.2",
"cross-env": "^5.1.4"
"cross-env": "^5.1.4",
"hast-util-to-html": "^6.0.2",
"mdast-util-to-hast": "^6.0.1"
},
"homepage": "https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-images#readme",
"keywords": [
Expand Down
64 changes: 64 additions & 0 deletions packages/gatsby-remark-images/src/__tests__/__snapshots__/index.js.snap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,70 @@ exports[`it uses tracedSVG placeholder when enabled 1`] = `
</span>"
`;

exports[`markdownCaptions display title in markdown as caption when showCaptions === true && markdownCaptions === true 1`] = `
"<figure class=\\"gatsby-resp-image-figure\\" style=\\"\\">
<span
class=\\"gatsby-resp-image-wrapper\\"
style=\\"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 300px;\\"
>
<a
class=\\"gatsby-resp-image-link\\"
href=\\"not-a-real-dir/images/my-image.jpeg\\"
style=\\"display: block\\"
target=\\"_blank\\"
rel=\\"noopener\\"
>
<span
class=\\"gatsby-resp-image-background-image\\"
style=\\"padding-bottom: 133.33333333333331%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw'); background-size: cover; display: block;\\"
></span>
<img
class=\\"gatsby-resp-image-image\\"
alt=\\"some alt\\"
title=\\"some _title_\\"
src=\\"not-a-real-dir/images/my-image.jpeg\\"
srcset=\\"not-a-real-dir/images/my-image.jpeg, not-a-real-dir/images/my-image.jpeg\\"
sizes=\\"(max-width: 650px) 100vw, 650px\\"
loading=\\"lazy\\"
/>
</a>
</span>
<figcaption class=\\"gatsby-resp-image-figcaption\\"><p>some <em>title</em></p></figcaption>
</figure>"
`;
exports[`markdownCaptions display title in text as caption when showCaptions === true && markdownCaptions === false 1`] = `
"<figure class=\\"gatsby-resp-image-figure\\" style=\\"\\">
<span
class=\\"gatsby-resp-image-wrapper\\"
style=\\"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 300px;\\"
>
<a
class=\\"gatsby-resp-image-link\\"
href=\\"not-a-real-dir/images/my-image.jpeg\\"
style=\\"display: block\\"
target=\\"_blank\\"
rel=\\"noopener\\"
>
<span
class=\\"gatsby-resp-image-background-image\\"
style=\\"padding-bottom: 133.33333333333331%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw'); background-size: cover; display: block;\\"
></span>
<img
class=\\"gatsby-resp-image-image\\"
alt=\\"some alt\\"
title=\\"some _title_\\"
src=\\"not-a-real-dir/images/my-image.jpeg\\"
srcset=\\"not-a-real-dir/images/my-image.jpeg, not-a-real-dir/images/my-image.jpeg\\"
sizes=\\"(max-width: 650px) 100vw, 650px\\"
loading=\\"lazy\\"
/>
</a>
</span>
<figcaption class=\\"gatsby-resp-image-figcaption\\">some _title_</figcaption>
</figure>"
`;
exports[`showCaptions display alt as caption if specified first in showCaptions array 1`] = `
"<figure class=\\"gatsby-resp-image-figure\\" style=\\"\\">
<span
Expand Down
55 changes: 55 additions & 0 deletions packages/gatsby-remark-images/src/__tests__/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ const Remark = require(`remark`)
const { Potrace } = require(`potrace`)
const queryString = require(`query-string`)
const cheerio = require(`cheerio`)
const toHAST = require(`mdast-util-to-hast`)
const hastToHTML = require(`hast-util-to-html`)

const plugin = require(`../`)

Expand Down Expand Up @@ -71,6 +73,10 @@ const createPluginOptions = (content, imagePaths = `/`) => {
dir: dirName,
}
},
compiler: {
parseString: remark.parse.bind(remark),
generateHTML: node => hastToHTML(toHAST(node)),
},
}
}

Expand Down Expand Up @@ -532,3 +538,52 @@ describe(`showCaptions`, () => {
expect(node.value).toMatchSnapshot()
})
})

describe(`markdownCaptions`, () => {
it(`display title in markdown as caption when showCaptions === true && markdownCaptions === true`, async () => {
const imagePath = `images/my-image.jpeg`
const content = `![some alt](./${imagePath} "some _title_")`

const nodes = await plugin(createPluginOptions(content, imagePath), {
showCaptions: true,
markdownCaptions: true,
})
expect(nodes.length).toBe(1)

const node = nodes.pop()
const $ = cheerio.load(node.value)
expect($(`figcaption`).html()).toEqual(`<p>some <em>title</em></p>`)
expect(node.value).toMatchSnapshot()
})

it(`display title in text as caption when showCaptions === true && markdownCaptions === false`, async () => {
const imagePath = `images/my-image.jpeg`
const content = `![some alt](./${imagePath} "some _title_")`

const nodes = await plugin(createPluginOptions(content, imagePath), {
showCaptions: true,
markdownCaptions: false,
})
expect(nodes.length).toBe(1)

const node = nodes.pop()
const $ = cheerio.load(node.value)
expect($(`figcaption`).html()).toEqual(`some _title_`)
expect(node.value).toMatchSnapshot()
})

it(`display nothing as caption when showCaptions === false && markdownCaptions === true`, async () => {
const imagePath = `images/my-image.jpeg`
const content = `![some alt](./${imagePath} "some _title_")`

const nodes = await plugin(createPluginOptions(content, imagePath), {
showCaptions: false,
markdownCaptions: true,
})
expect(nodes.length).toBe(1)

const node = nodes.pop()
const $ = cheerio.load(node.value)
expect($(`figcaption`).length).toBe(0)
})
})
1 change: 1 addition & 0 deletions packages/gatsby-remark-images/src/constants.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ exports.DEFAULT_OPTIONS = {
backgroundColor: `white`,
linkImagesToOriginal: true,
showCaptions: false,
markdownCaptions: false,
withWebp: false,
tracedSVG: false,
loading: `lazy`,
Expand Down
71 changes: 45 additions & 26 deletions packages/gatsby-remark-images/src/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,16 @@ const chalk = require(`chalk`)
// 4. Create the responsive images.
// 5. Set the html w/ aspect ratio helper.
module.exports = (
{ files, markdownNode, markdownAST, pathPrefix, getNode, reporter, cache },
{
files,
markdownNode,
markdownAST,
pathPrefix,
getNode,
reporter,
cache,
compiler,
},
pluginOptions
) => {
const options = _.defaults(pluginOptions, { pathPrefix }, DEFAULT_OPTIONS)
Expand Down Expand Up @@ -73,33 +82,43 @@ module.exports = (
}

const getImageCaption = (node, overWrites) => {
const captionOptions = Array.isArray(options.showCaptions)
? options.showCaptions
: options.showCaptions === true
? [`title`, `alt`]
: false

if (captionOptions) {
for (const option of captionOptions) {
switch (option) {
case `title`:
if (node.title) {
return node.title
}
break
case `alt`:
if (overWrites.alt) {
return overWrites.alt
}
if (node.alt) {
return node.alt
}
break
const getCaptionString = () => {
const captionOptions = Array.isArray(options.showCaptions)
? options.showCaptions
: options.showCaptions === true
? [`title`, `alt`]
: false

if (captionOptions) {
for (const option of captionOptions) {
switch (option) {
case `title`:
if (node.title) {
return node.title
}
break
case `alt`:
if (overWrites.alt) {
return overWrites.alt
}
if (node.alt) {
return node.alt
}
break
}
}
}

return ``
}

const captionString = getCaptionString()

if (!options.markdownCaptions || !compiler) {
return _.escape(captionString)
}

return ``
return compiler.generateHTML(compiler.parseString(captionString))
}

// Takes a node and generates the needed images and then returns
Expand Down Expand Up @@ -166,7 +185,7 @@ module.exports = (
reporter.stripIndent(`
${chalk.bold(loading)} is an invalid value for the ${chalk.bold(
`loading`
)} option. Please pass one of "lazy", "eager" or "auto".
)} option. Please pass one of "lazy", "eager" or "auto".
`)
)
}
Expand Down Expand Up @@ -261,7 +280,7 @@ module.exports = (

// Construct new image node w/ aspect ratio placeholder
const imageCaption =
options.showCaptions && _.escape(getImageCaption(node, overWrites))
options.showCaptions && getImageCaption(node, overWrites)

let rawHTML = `
<span
Expand Down
8 changes: 8 additions & 0 deletions packages/gatsby-transformer-remark/src/extend-node-type.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,10 @@ module.exports = (
reporter,
cache: getCache(plugin.name),
getCache,
compiler: {
parseString: remark.parse.bind(remark),
generateHTML: getHTML,
},
...rest,
},
plugin.pluginOptions
Expand Down Expand Up @@ -229,6 +233,10 @@ module.exports = (
reporter,
cache: getCache(plugin.name),
getCache,
compiler: {
parseString: remark.parse.bind(remark),
generateHTML: getHTML,
},
...rest,
},
plugin.pluginOptions
Expand Down

0 comments on commit a72cbaf

Please sign in to comment.