open-ephys / bonsai-onix1-docs

Documentation for the OpenEphys.Onix1 Bonsai package
https://open-ephys.github.io/bonsai-onix1-docs/
Creative Commons Attribution Share Alike 4.0 International
0 stars 2 forks source link

Add files for making custom captioned containers #44

Closed cjsha closed 3 weeks ago

cjsha commented 1 month ago

The syntax is like:

:::image-caption
![brief description of image](path/to/image.webp)

this is the caption
:::
:::workflow-caption
![brief description of workflow](path/to/workflow.bonsai)

this is the caption
:::

If this is clunky, maybe it's better to add html directly to the markdown file. I'm not necessarily opposed to just doing that if it works and doesn't create any issues with the linkchecking process or anything like that

jonnew commented 1 month ago

Trying this out and this is what I see:

image

Do I need to perform a clean build or something, maybe?

cjsha commented 1 month ago

Pull the latest commit and look at the headstage64-tut.md file to look at examples. Deleting the "_site" for a clean build might help this time to remove a certain local .css file.

With that said, I'd like to point you to this relevant comment about whether we should write in HTML or make custom containers. I suppose frequently repeated HTML should be its own custom markdown container.

cjsha commented 3 weeks ago

@jonnew Captions are supported in markdig markdown engine (which docfx uses), but need to be enabled in the docfx.json by adding "figures" to the "markdigExtensions" array

    "markdownEngineName": "markdig",
    "markdownEngineProperties": {
      "markdigExtensions": [
        "attributes",
        "customcontainers",
        "figures"
      ],
      "alerts": {
        "TODO": "alert alert-secondary"
      }
    },

Do that ^ and follow this syntax to generate captions. I tested it, it works. This can be used to caption workflows, images, videos, etc., so I'm going to close this PR.