Skip to content

Images

Jump to bottom
Karl Voit edited this page Dec 26, 2021 · 9 revisions

Orgmode Elements > Images

You have three different possibilities to embed images to a blog post:

  1. Using a standard HTML snippet
  2. Using the proposed tsfile: custom link using a defined set of folders to search for images (DIRECTORIES_WITH_IMAGE_ORIGINALS) only
  3. Using the proposed tsfile: custom link using a defined set of folders to search for images (DIRECTORIES_WITH_IMAGE_ORIGINALS) and also using your Memacs index of the filenametimestamps module

Of course, HTML snippets always work. You can combine all three methods above.

The easiest to start with is the HTML snippet method. The downside is, that you have to link to publicly available images.

The tsfile: method with a simple lookup within DIRECTORIES_WITH_IMAGE_ORIGINALS is quite easy to set-up. You just have to make sure that all linked images are within the set of defined folders. This also comes with the algorithm that finds your files even when they are renamed by tagging. See “Smart tsfile Image File Search” below for details.

The tsfile: method in combination with Memacs has a huge advantage: You don’t have to worry again, where your image files are located. You can even move them around within your file system without breaking any links on your blog. Indexing your files is done by Memacs.

Embedding Images via HTML

Using HTML snippets you can embed image files hosted on the web via HTML snippets such as:

#+BEGIN_EXPORT html
<img src="http://example.com/images/Joshua_Tree.jpg" alt="A beautiful tree" />
#+END_EXPORT

However, not all images can be found on the public internet and those links are not stable. Therefore, you want to host images on your own blog.

Following chapter describes your possibilities to embed image files that are located on your computer and which should get copied and published with your blog data as well.

Configuration

In config.py you do have three options to configure related to images:

  1. CUSTOMIZED_IMAGE_LINK_KEY
  2. MEMACS_FILE_WITH_IMAGE_FILE_INDEX
    • Read the Memacs readme to learn about Memacs and its filenametimestamps module.
    • Basically it’s a path to a text file (the Memacs index) that holds lines like: 
      ** <2006-01-06 10:16> [[2006-01-06 My Document.pdf|/home/user/projects/foobar/2006-01-06 My Document.pdf]]
    • All links to files within the Memacs index are indexed for lazyblorg images as well.
      • You should exclude the directories with your generated blog data from being indexed by Memacs.
    • Use an empty string to disable the Memacs index for lazyblorg.
  3. DIRECTORIES_WITH_IMAGE_ORIGINALS
    • This is the good old-fashioned method: add a list entry to a relative or an absolute path to a directory. This directory and all of its sub-directories are traversed and all filenames are indexed for lazyblorg images.
    • Use an empty list to disable including images via traversing the file system.
  4. IMAGE_CACHE_DIRECTORY
    • This optional directory holds a path to an existing folder which is used to copy images that were resized too meet the width stated by the user (ATTR_HTML below).
    • To speed up blog data generation time, the resized images that have a more recent modification time compared to the original file are stored here and copied to the target directory on blog data generation time.
    • It is an empty string or a non-existing path if image cache is disabled.

So if you want to embed image files, you must configure CUSTOMIZED_IMAGE_LINK_KEY and at least one of the other options (Memacs and/or directory traversal) as well.

Embedding tsfile Image Files

For embedding image files via the tsfile: method, you have many options that provides you a maximum of flexibility.

Basics

The simplest one: a tsfile-link to an image file

[[tsfile:2017-03-11T18.29.21 Stars at night -- mytag.jpg]]

As you can see, you don’t have to cope with the directory, where the image file is located. Using the Memacs and/or the file traversal method, image files are located and copied independent of their current location.

This is quite handy when image files are moved between different directories or directories are renamed on the way.

On the downside, you get random results when using the very same file name for different image files. However, I tend to classify this as an edge-case.

Of course, you can use your Org-mode link description as usual:

[[tsfile:2017-03-11T18.29.21 Stars at night -- mytag.jpg][This photo of stars at night is awesome]]

The description This photo of stars at night is awesome becomes the HTML caption of the image in the blog.

If the link description is an URL, the whole image will be a link to that URL:

[[tsfile:2017-03-11T18.29.21 Stars at night -- mytag.jpg][https://Karl-Voit.at]]

Captions, Alt-Text, Width and Alignment

But hey, there so much more: You can use the #+CAPTION: feature as well. This will supersede the Org-mode link description. Parameters within #+ATTR_HTML: can be used to define alt text, alignment, or the width of an image:

#+CAPTION: Some beautiful stars in a tree
#+ATTR_HTML: :alt Stars in a Tree :align right :width 300
[[tsfile:2017-03-11T18.29.21 Stars at night -- mytag.jpg][This description is superseded by the CAPTION line]]

This results in HTML code like following:

<figure class="image-right">
<img src="2017-03-11T18.29.21 Stars at night -- mytag - scaled width 300.jpg" alt="Stars in a Tree" width="300" />
<figcaption>Some beautiful stars in a tree<figcaption/>
</figure>

As you can see, when using the width attribute, the resulting image is also scaled to this width in order to maximize transmission speed and browser performance. Currently, there is only support for defining the width and not the height.

If you do not provide a width attribute, the original image is embedded without changes. This may result in large transfer volume and slow page performance. This also exposes all meta-data of the photograph such as GPS location, time-stamps, details about your digital camera, and so forth.

When the image is scaled using a width parameter, a new, fresh image is created without the meta-data of the original image, preserving your privacy as well.

You can use multiple ATTR_HTML lines to define multiple parameters in multiple lines:

#+CAPTION: This is going to be the caption
#+ATTR_HTML: :alt This is going to be the alt parameter of the img tag
#+ATTR_HTML: :title The title (like all other "unknown" attributes) is ignored
#+ATTR_HTML: :align right :width 300
[[tsfile:2017-03-11T18.29.21 Stars at night -- mytag.jpg][Remember, if there is an CAPTION, this title gets ignored]]

Currently, lazyblorg supports following alignment parameters:

  • :align left
    • left-aligned image, nothing on the right hand side
  • :align right
    • right-aligned image, nothing on the left hand side
  • :align center
    • centered image, nothing on the right or left of it
    • This is the default alignment if there is no align parameter found.
  • :align float-left
    • left-aligned image where the follow-up paragraph floats around the image
  • :align float-right
    • right-aligned image where the follow-up paragraph floats around the image

Be careful with the float- options: be sure to follow-up those images with paragraphs that contain enough text to float until the bottom of the image. Otherwise, there could be overlapping page elements.

Linking a Larger Image Version

You can decide to include a scaled smaller image to the blog article as explained above. Additionally, lazyblorg offers you the possibility to link a different sized image. This enables the reader to click on a small image in order to get a bigger version. To do so, you have to use an additional ATTR_HTML parameter to define the size of the linked image: linked-image-width which looks like this:

#+ATTR_HTML: :width 200 :linked-image-width 1500
[[tsfile:2017-03-11T18.29.21 Stars at night -- mytag.jpg][Remember, if there is an CAPTION, this title gets ignored]]

This example would insert the image with 200 pixel width. When clicking on this small image, the user is shown the same image with 1500 pixel width.

Allowed values for the linked-image-width parameter are: none or original or an integer value greater than zero. The value none omits the linked image which reflects the same as omitting the linked-image-width parameter altogether. The value original links the image in its original size, without scaling. If you set the value to a number, the linked image width gets scaled to this number of pixels.

In the config.py you may modify CLUE_TEXT_FOR_LINKED_IMAGES which contains textual clues for the page reader that there is a linked image to click on. You may change the styling for it by modifying .figcaption-clue-link within the SCSS template.

Please note that you must not use a width attribute other than none when the link description is an URL.

Images Without Exif Metadata

Any embedded or linked images via the tsfile: method get stripped from their Exif metadata. This ensures a maximum level of privacy without leaking the camera you were using, the date and time when you took the photograph and the GPS coordinates.

Smart tsfile Image File Search

If you do use a similar image management method to mine, you might face following situation as well. You have taken a great photograph and renamed it 2017-03-11T18.29.21 Stars at night.jpg which is a reasonable choice.

You’re embedding this photograph in a blog article:

[[tsfile:2017-03-11T18.29.21 Stars at night.jpg][What a beautiful night]]

A few weeks later, you decide to add some tags to the files from the recent photo sessions. During this task, the image file from your blog post gets renamed and now has a filetag such as: 2017-03-11T18.29.21 Stars at night -- tree night springbreak.jpg

Normally, this would result in a broken link in your lazyblorg blog article. But lazyblorg is not normal: I’ve implemented an algorithm that detects that the file starts with an adapted ISO time-stamp: 2017-03-11T18.29.21.

If there is another unique filename that starts with the very same time-stamp, this file is assumed to be the same image file as stated in the Org-mode source of the blog article. In this case, lazyblorg prints out a warning in the logs and uses this image file instead of the broken filename.

Isn’t this great? I’m loving it!

Easy Embedding Images with a Yasnippet Snippet

If you are as lazy as I am (at least you’re using a blog software that contains the word «lazy» in its name!) you won’t type all those things on your own.

I’m sure you already know yasnippet and its virtues.

In this case, a snippet might look like following:

# name : ATTR_HTML block with CAPTION for lazyblorg images
# --
#+CAPTION: ${3:caption}
#+ATTR_HTML: :alt ${4:alterantive-text for the image}
#+ATTR_HTML: :align ${5:$$(yas-choose-value '("left" "center" "right" "float-left" "float-right"))} :width ${6:width in pixel} :linked-image-width ${7:none, original or width in pixel}
[[tsfile:$1][: ${2:$$(unless yas-modified-p
 (let ((field (nth 0 (yas--snippet-fields (first (yas--snippets-at-point))))))
   (concat (buffer-substring (yas--field-start field) (yas--field-end field)))))}]] $0

It asks you for all parameters and generates a perfectly fine result for your blog article.

Enjoy.

Home

Using lazyblorg:

Coding:

Clone this wiki locally