Creating captions for images?

[cmdcolin]

Is there any concept for creating captions for an image in plain markdown? MDX may also work if that is simply better, although we've tried to keep things mostly plain markdown at this point

[cmdcolin]

Went ahead and did some MDX :)

I created figures.jsx

/* eslint-disable react/prop-types,import/no-unresolved */
import React from 'react'
import useBaseUrl from '@docusaurus/useBaseUrl'

export default function Figure({ src, caption }) {
  return (
    <figure style={{ border: '1px solid #888', padding: 20 }}>
      <img src={useBaseUrl(src)} alt={caption} />
      <figcaption>{`Figure: ${caption}`}</figcaption>
    </figure>
  )
}

Then in my markdown/mdx files I use

import Figure from './figure'
<Figure caption="Caption for my picture" src="/img/mypicture.png" />

[MyBaBB]

I have been working and tried several angles. This is the way others would do it but, I don't think that is the goal. I have gotten close several times but it always throws an error. We could make a real fancy one that way with some added css though. It's bugging me real bad because this is the only loose end that I have..I think that it is just because we are in Docusaurus. From my understanding he wants it to be a custom Markdown line. So that more markdown writers can just write markdown easily.
Maybe in the future we can Move the whole website to another platform that is more customizable. There are other options available that allow for more customizations. That would be a huge project but the future is here.
If we could figure it out - it would be great, I am thinking that by the time they learn how to do all that, they could have just learned the html version easier.

[slorber]

@MyBaBB I'm not sure to understand your comment, but you can pass remark/rehype plugins so technically you can invent your own syntax.

For example with remark directive and a bit of remark code, you could enable such syntax:

::img[Caption for my picture]{src="/img/mypicture.png"}

Docusaurus is flexible, it's just that we don't provide absolutely everything out of the box, and we let you have your own opinions and implement things yourself sometimes.

[Sugamgoel28]

@slorber Interested to know how to implemented ::img[Caption for my picture]{src="/img/mypicture.png"} using remark. Would you like to share more about it?

[slorber]

@Sugamgoel28 Docusaurus already uses remark-directive so the above syntax is already parsed to proper AST nodes:

Now you can write a remark plugin that takes this kind of node as input and transforms it to whatever JSX you want.

function myRemarkPlugin() {
  return async (root) => {
    const {visit} = await import('unist-util-visit');
    visit(root, (node) => {
      if (node.type === 'leafDirective' && directive.name === "img") {
        transformDirective(node);
      }
    });
  };
};

You just have to write the transformDirective function to transform directive nodes to JSX nodes.

That's a bit out of scope for me to teach you how to write remark plugins. There's the remark doc for that.

I'd advise using the MDX playground extensively to know what's the input nodes, and what's the output you need to emit.

Input is:

Output is probably something like this:

So basically your transform function should transform this:

  {
      "type": "leafDirective",
      "name": "img",
      "attributes": {
        "src": "/img/mypicture.png"
      },
      "children": [
        {
          "type": "text",
          "value": "Caption for my picture"
        }
      ]
    }

Into this:

  {
      "type": "mdxJsxFlowElement",
      "name": "figure",
      "attributes": [],
      "children": [
        {
          "type": "mdxJsxFlowElement",
          "name": "img",
          "attributes": [
            {
              "type": "mdxJsxAttribute",
              "name": "src",
              "value": "/img/mypicture.png",
              "position": {
            }
          ],
          "children": [],
        },
        {
          "type": "mdxJsxFlowElement",
          "name": "figcaption",
          "attributes": [],
          "children": [
            {
              "type": "text",
              "value": "Caption for my picture"
            }
          ],
        }
      ],
    }

[GambitFPS]

.jsx has to be placed where? inside docs?

[cmdcolin]

yep, this is my layout: docs/figure.jsx

import React from 'react'
import useBaseUrl from '@docusaurus/useBaseUrl'

export default function Figure({ src, caption }) {
  return (
    <figure style={{ border: '1px solid #888', padding: 20 }}>
      <img src={useBaseUrl(src)} alt={caption} />
      <figcaption>{`Figure: ${caption}`}</figcaption>
    </figure>
  )
}

And then in the markdown files like docs/user_guide.md

---
id: user_guide
title: User guide
---

import Figure from './figure'

## Header here

Here is a figure

<Figure caption="Figure caption" src="/img/myimage.png" />

[slorber]

You can also put it anywhere you want, and use an import such as import Figure from '@site/src/components/figure'

[zeluspudding]

Hey there! I've tried following these (fairly straight forward) recommendations but can't seem to get this component to import in my .md file. Wrote up the full issue here on Stackoverflow (with a fully reproducible example on stackblitz). Anyone think they know the issue? Thank you in advance!

[cmdcolin]

I tried changing your import to use import Figure from '../components/figures' and it appeared to work, i think this is a fork https://stackblitz.com/edit/github-5c7qs5-u13hp6?file=docs%2Ftheirlabel%2Flatest.md,docs%2Fscious-search%2Flatest.md

[zeluspudding]

That was exactly the issue! Thank you so much for the pointer!! Any way I can send you a tip (perhaps using Basic Attention Token?.. we have a built in tipping mechanic in Brave that I've been wanting to use in github)? Just let me know :)

[cmdcolin]

no worries, don't need a tip though that is a cool idea :) you made it very easy to diagnose with the reproducible example!

[zeluspudding]

I know! Stackblitz is incredible :) Am developing directly on there, then syncing with github which auto-triggers deploys to production as code hits master. This was the first time I did this but, yeah, the second debugging hits a wall it's dead simple to share with the world for help. Thank you again so much!

[horsfallnathan]

Hi! Using the component doesn't seem to work for relative paths. I have an img directory for each doc content. Any help will be appreciated. My docs tree looks like this:

├── docs
│   ├── topicRoot
│   │   ├── topic.mdx
│   │   ├── _category_.json
│   │   ├── img
│   │   │   └── topicImg.png

I tried using various variations of <Figure src="./img/topicImg.png" caption="some caption" /> and the image file isn't found.

[xendarboh]

Example current implementation that works conveniently with relative image paths:

src/components/Figures/index.tsx:

import styles from './styles.module.css';

// https://github.com/facebook/docusaurus/discussions/4633
export default function Figure({src, caption}) {
  return (
    <div>
      <figure>
        <img src={src} alt={caption} />
        <figcaption className={styles.figcaption}>{caption}</figcaption>
      </figure>
    </div>
  );
}

src/components/Figures/styles.module.css:

.figcaption {
  text-align: center;
  font-style: italic;
}

docs/example.md:

---
sidebar_position: 101
---

import Figure from '@site/src/components/Figures';

import figure1 from './img/figure1.webp';

# Figure Caption Example

<Figure caption="In the time of chimpanzees..." src={figure1} />

[YoniChechik]

This is how did it:

import Image from '@theme/IdealImage';
import thumbnail from '../../static/img/2023-04-06-19-19-47.png';
import CaptionWrapper from "@site/src/components/CaptionWrapper";
<CaptionWrapper caption="Variables are easy......">
<Image img={thumbnail} alt="variables joke"/>
</CaptionWrapper>

and the js:

import React from "react";
import styles from "./CaptionWrapper.module.css";
export default function CaptionWrapper(props) {
  return (
    <figure>
      {props.children}
      <figcaption className={styles.figcaption}>{props.caption}</figcaption>
    </figure>
  );
}

css:

.figcaption {
  text-align: center;
  font-style: italic;
  color: #828282;
}