I am hosting a Jekyll Blog on Github and write my posts with Markdown. When I am adding images, I do it the following way:
This then shows the image in the text.
However, how can I tell Markdown to add a caption which is presented below or above the image?
If you don't want to use any plugins (which means you can push it to GitHub directly without generating the site first), you can create a new file named image.html in _includes:
<figure class="image">
<img src="{{ include.url }}" alt="{{ include.description }}">
<figcaption>{{ include.description }}</figcaption>
</figure>
And then display the image from your markdown with:
{% include image.html url="/images/my-cat.jpg" description="My cat, Robert Downey Jr." %}
I know this is an old question but I thought I'd still share my method of adding image captions. You won't be able to use the caption or figcaption tags, but this would be a simple alternative without using any plugins.
In your markdown, you can wrap your caption with the emphasis tag and put it directly underneath the image without inserting a new line like so:
*image_caption*
This would generate the following HTML:
<p>
<img src="path_to_image" alt>
<em>image_caption</em>
</p>
Then in your CSS you can style it using the following selector without interfering with other em tags on the page:
img + em { }
Note that you must not have a blank line between the image and the caption because that would instead generate:
<p>
<img src="path_to_image" alt>
</p>
<p>
<em>image_caption</em>
</p>
You can also use whatever tag you want other than em. Just make sure there is a tag, otherwise you won't be able to style it.
The correct HTML to use for images with captions, is <figure> with <figcaption>.
There's no Markdown equivalent for this, so if you're only adding the occasional caption, I'd encourage you to just add that html into your Markdown document:
Lorem ipsum dolor sit amet, consectetur adipiscing elit...
<figure>
<img src="{{site.url}}/assets/image.jpg" alt="my alt text"/>
<figcaption>This is my caption text.</figcaption>
</figure>
Vestibulum eu vulputate magna...
The Markdown spec encourages you to embed HTML in cases like this, so it will display just fine. It's also a lot simpler than messing with plugins.
If you're trying to use other Markdown-y features (like tables, asterisks, etc) to produce captions, then you're just hacking around how Markdown was intended to be used.
A slight riff on the top voted answer that I found to be a little more explicit is to use the jekyll syntax for adding a class to something and then style it that way.
So in the post you would have:
{:.image-caption}
*The caption for my image*
And then in your CSS file you can do something like this:
.image-caption {
text-align: center;
font-size: .8rem;
color: light-grey;
Comes out looking good!
There are two semantically correct solutions to this question:
I've tried a couple of plugins doing this and my favourite is jekyll-figure.
jekyll-figureOne way to install jekyll-figure is to add gem "jekyll-figure" to your Gemfile in your plugins group.
Then run bundle install from your terminal window.
jekyll-figureSimply wrap your markdown in {% figure %} and {% endfigure %} tags.
You caption goes in the opening {% figure %} tag, and you can even style it with markdown!
Example:
{% figure caption:"Le logo de **Jekyll** et son clin d'oeil à Robert Louis Stevenson" %}
{% endfigure %}
Now that your images and captions are semantically correct, you can apply CSS as you wish to:
figure (for both image and caption)figure img (for image only)figcaption (for caption only)You'll need to create an image.html file in your _includes folder, and include it using Liquid in Markdown.
Create the image.html document in your _includes folder :
<!-- _includes/image.html -->
<figure>
{% if include.url %}
<a href="{{ include.url }}">
{% endif %}
<img
{% if include.srcabs %}
src="{{ include.srcabs }}"
{% else %}
src="{{ site.baseurl }}/assets/images/{{ include.src }}"
{% endif %}
alt="{{ include.alt }}">
{% if include.url %}
</a>
{% endif %}
{% if include.caption %}
<figcaption>{{ include.caption }}</figcaption>
{% endif %}
</figure>
An image in /assets/images with a caption:
This is [Jekyll](https://jekyllrb.com)'s logo :
{% include image.html
src="jekyll-logo.png" <!-- image filename (placed in /assets/images) -->
alt="Jekyll's logo" <!-- alt text -->
caption="This is Jekyll's logo, featuring Dr. Jekyll's serum!" <!-- Caption -->
%}
An (external) image using an absolute URL: (change src="" to srcabs="")
This is [Jekyll](https://jekyllrb.com)'s logo :
{% include image.html
srcabs="https://jekyllrb.com/img/logo-2x.png" <!-- absolute URL to image file -->
alt="Jekyll's logo" <!-- alt text -->
caption="This is Jekyll's logo, featuring Dr. Jekyll's serum!" <!-- Caption -->
%}
A clickable image: (add url="" argument)
This is [Jekyll](https://jekyllrb.com)'s logo :
{% include image.html
src="https://jekyllrb.com/img/logo-2x.png" <!-- absolute URL to image file -->
url="https://jekyllrb.com" <!-- destination url -->
alt="Jekyll's logo" <!-- alt text -->
caption="This is Jekyll's logo, featuring Dr. Jekyll's serum!" <!-- Caption -->
%}
An image without a caption:
This is [Jekyll](https://jekyllrb.com)'s logo :
{% include image.html
src="https://jekyllrb.com/img/logo-2x.png" <!-- absolute URL to image file -->
alt="Jekyll's logo" <!-- alt text -->
%}
Now that your images and captions are semantically correct, you can apply CSS as you wish to:
figure (for both image and caption)figure img (for image only)figcaption (for caption only)You can try to use pandoc as your converter. Here's a jekyll plugin to implement this. Pandoc will be able to add a figure caption the same as your alt attribute automatically.
But you have to push the compiled site because github doesn't allow plugins in Github pages for security.
Andrew's @andrew-wei answer works great. You can also chain a few together, depending on what you are trying to do. This, for example, gets you an image with alt, title and caption with a line break and bold and italics in different parts of the caption:
img + br + strong {margin-top: 5px; margin-bottom: 7px; font-style:italic; font-size: 12px; }
img + br + strong + em {margin-top: 5px; margin-bottom: 7px; font-size: 12px; font-style:italic;}
With the following <img> markdown:
***Image:*** *description*
For Kramdown, you can use {:refdef: style="text-align: center;"} to align center
{:refdef: style="text-align: center;"}
{: width="50%" .shadow}
{: refdef}
{:refdef: style="text-align: center;"}
*Fig.1: This is an example image. [Source](https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg)*
{: refdef}
You need to add {::options parse_block_html="true" /} at the beginning of the post for this to work.
This option might seem complicated on the surface, but it is not at all and solves other problems that the Jekyll markdown renderer (Kramdown) has. Basically this option changes the renderer for one made with python that is expandable, allowing you to instally extensions (there are a ton, markdown-captions for example) and expand it (it has an extension API).
The first step is to define a custom markdown processor. You will have to add markdown: CustomProcessor to the _config.yml.
Then, we have to create the CustomProcessor. Create a folder called _plugins and add a file called MyConverter.rb with this content:
class Jekyll::Converters::Markdown::CustomProcessor
def initialize(config)
end
def matches(ext)
ext =~ /^\.(md|markdown)$/i
end
def output_ext(ext)
".html"
end
def convert(content)
puts "EXECUTED"
md_path = "./_plugins/temp/temp.md"
html_path = "./_plugins/temp/temp.html"
File.write(md_path, content, mode: "w")
system("python ./_plugins/MyConverter.py")
content = File.read(html_path)
content
end
end
You will also need to create a folder temp inside plugins.
All that code does is to write all the content of the file we are processing to temp.md, call a python script, wait until it finishes, read temp.html, and return it as the output of the converter.
MyConverter.py inside the _plugins folder and put this content inside:import markdown
markdown_extensions = [
'markdown_captions',
'def_list',
'nl2br',
'tables',
'codehilite',
'fenced_code',
'md_in_html',
'attr_list'
]
md_file = open("./_plugins/temp/temp.md", "r")
md_string = md_file.read()
md_file.close()
html_string = markdown.markdown(md_string, extensions=markdown_extensions, extension_configs =extension_configs)
html_file = open("./_plugins/temp/temp.html", "w")
html_file.write(html_string)
html_file.close()
That code just loads the extensions, reads temp.md file, converts it to html and writtes it to temp.html. Using all those extensions should generate a similar output to the default jekyll markdown rendere. The only extension that is not bundled with python-markdown is markdown_captions, the one that does the magic. To install the python renderer and the extension you just have to run pip install Markdown markdown-captions.
That should do it, now your markdown is being translated by Python-Markdown. Some html elements my be different now (in my experience just a few) so maybe you have to make small changes in the css.
This is the css that I am using with the camptions:
figure{
margin: 0px;
}
figcaption {
color: gray;
font-size: 0.8rem;
}
The process tries to be as simple as possible to make it easy to understand and modify. I have described the process as well as I could remember. If anybody has a problem just leave a comment and I will update the answer.
Add the following config in the _config.yml file
# prose.io config
prose:
rooturl: '_posts'
media: 'img'
ignore:
- 404.html
- LICENSE
- feed.xml
- _config.yml
- /_layouts
- /_includes
- /css
- /img
- /js
metadata:
_posts:
- name: "layout"
field:
element: "hidden"
value: "post"
- name: "title"
field:
element: "text"
label: "Post title"
placeholder: "Title"
alterable: true
- name: "subtitle"
field:
element: "textarea"
label: "Subtitle"
placeholder: "A description of your post."
alterable: true
- name: "date"
field:
element: "text"
label: "Date"
help: "Enter date of post."
placeholder: "yyyy-mm-dd"
alterable: true
- name: "image"
field:
element: "text"
label: "Image"
help: "Add a thumbnail image to your post."
placeholder: "Thumbnail"
alterable: true
- name: "published"
field:
element: "checkbox"
label: "Publish"
help: "Check to publish post, uncheck to hide."
