Differences and best practices: files vs images vs galleries

[Mariano Draghi]

Hi,

TL;DR: I have several posts with embedded images, and I can't decide where to put the image files (FILES_FOLDER vs IMAGE_FOLDER vs GALLERY_FOLDERS), and whether I should use relative or absolute paths when linking from reST.

I'm new to Nikola, although I've been more or less following its development for a long time. I've finally gathered the motivation to migrate from a self-hosted WordPress instance in a shared web hosting service (which in turn was a self-hosted LifeType (formerly pLog) instance), to a nikola instance in a VPS.

The migration was pretty straightforward (kudos to humitos and others for sharing their experience), and I'm now in the process of reviewing all the posts and using a combination of ad-hoc scripts, sed kung-fu and manual edition to polish all the details.

And I'm really struggling to decide which is the best way to embed single, local images, in a post.

For now I copied over the contents of my former "imgs" folder from WordPress inside the "images" folder in nikola. But I don't like that the images ended up in the root folder, with the posts. I suspect that's because IMAGE_FOLDER by default is {'images': ''}. Should I go for something like {'images': 'images'} instead?

Then, when I reference the file in reST, I can use an absolute path, like '/foobar.jpg', or a relative one, like '../foobar.jpg'. I know both work, but which is better in the long run?

Apart from the thumbnail generation, is there any other difference between having the images on a FILES_FOLDER or an IMAGE_FOLDER? If I want to just link an image, and I don't want a thumbnail, FILES_FOLDER seems a better choice. I'm leaning slightly towards the "files" folder... but as Nikola has specific folders/features dealing with images, I'm not 100% sure.

I've been looking around in GitHub for examples of what others are doing, and I've found that some people throw their imgaes in the gallery folder, and then link from there. It doesn't make much sense doing that for single images (i.e., if there is just one image on the post, or there are several unrelated ones). Am I missing something? Doesn't nikola treat the GALLERY_FOLDERS contents different?

You might say "Nikola is flexible, do what's best for you". But I can make it work with any of the alternatives, and I can't find the clear winner. I suppose I'm looking for some consensus, and for some insight on the intended use case for each of these features/alternatives to help me make up my mind :)

Thanks for your advice and ideas!

[Chris Warrick]

On Wed, Apr 22, 2015 at 5:10 PM, Mariano Draghi <mdr...@gmail.com> wrote:
> Hi,
>
> TL;DR: I have several posts with embedded images, and I can't decide where
> to put the image files (FILES_FOLDER vs IMAGE_FOLDER vs GALLERY_FOLDERS),
> and whether I should use relative or absolute paths when linking from reST.
>

> [snip]

>
> And I'm really struggling to decide which is the best way to embed single,
> local images, in a post.
>
> For now I copied over the contents of my former "imgs" folder from WordPress
> inside the "images" folder in nikola. But I don't like that the images ended
> up in the root folder, with the posts. I suspect that's because IMAGE_FOLDER
> by default is {'images': ''}. Should I go for something like {'images':
> 'images'} instead?

Yes. I believe we could change the default config to this. Doing
that for the next version (for new sites only!).

https://github.com/getnikola/nikola/pull/1663

> Then, when I reference the file in reST, I can use an absolute path, like
> '/foobar.jpg', or a relative one, like '../foobar.jpg'. I know both work,
> but which is better in the long run?

Using an absolute path will be safer and easier. Nikola will actually
convert it to a relative path* and figure things out intelligently
(for example, it will point to a resource under your site even if you
are not deploying to the web server root). Writing a relative path
yourself can break things if your output structure changes (Nikola
won’t ever do it, you could if you get bored with the defaults or want
to reproduce WP-style /year/month/day/ if you haven’t already**).
Besides, why bother counting dots?

> Apart from the thumbnail generation, is there any other difference between
> having the images on a FILES_FOLDER or an IMAGE_FOLDER? If I want to just
> link an image, and I don't want a thumbnail, FILES_FOLDER seems a better
> choice. I'm leaning slightly towards the "files" folder... but as Nikola has
> specific folders/features dealing with images, I'm not 100% sure.

In this case, it does not matter which one you use. Using /files/
would only save you a few (mega)bytes of disk space and a few CPU
cycles because thumbnails won’t be generated.

> I've been looking around in GitHub for examples of what others are doing,
> and I've found that some people throw their imgaes in the gallery folder,
> and then link from there. It doesn't make much sense doing that for single
> images (i.e., if there is just one image on the post, or there are several
> unrelated ones). Am I missing something? Doesn't nikola treat the
> GALLERY_FOLDERS contents different?

Image folders were added only recently, these examples might be too
old to reflect that — and we didn’t do much marketing for the feature.

Files in /galleries/ can be freely browsed by anyone in a nice gallery
interface (duh!), /images/ are not but still have thumbnails, /files/
are just simply copied without any processing at all.

> You might say "Nikola is flexible, do what's best for you". But I can make
> it work with any of the alternatives, and I can't find the clear winner. I
> suppose I'm looking for some consensus, and for some insight on the intended
> use case for each of these features/alternatives to help me make up my mind
> :)
>
> Thanks for your advice and ideas!

I would just use /images/ in this case. You may want to use
thumbnails one day, and it will just look cleaner in your structure.

* with URL_TYPE = 'rel_path' (default config)
** cool URLs don’t change, it’s nice if you keep the same URL
structure. changing PRETTY_URLS and POSTS in config + manually
creating the year/month/day directories under posts will do it.

--
Chris Warrick <https://chriswarrick.com/>
PGP: 5EAAEA16

[Mariano Draghi]

On Wednesday, April 22, 2015 at 12:38:29 PM UTC-3, Chris Warrick wrote:

On Wed, Apr 22, 2015 at 5:10 PM, Mariano Draghi <mdr...@gmail.com> wrote:
>

> [snip]

>
> For now I copied over the contents of my former "imgs" folder from WordPress
> inside the "images" folder in nikola. But I don't like that the images ended
> up in the root folder, with the posts. I suspect that's because IMAGE_FOLDER
> by default is {'images': ''}. Should I go for something like {'images':
> 'images'} instead?

Yes.  I believe we could change the default config to this.  Doing
that for the next version (for new sites only!).

https://github.com/getnikola/nikola/pull/1663

Ok, makes sense
This was also covered in a recent thread that somehow I missed: https://groups.google.com/d/topic/nikola-discuss/iy1wcsl8JmA/discussion (it seems I don't know how to search :p)

 

> Then, when I reference the file in reST, I can use an absolute path, like
> '/foobar.jpg', or a relative one, like '../foobar.jpg'. I know both work,
> but which is better in the long run?

Using an absolute path will be safer and easier.  Nikola will actually
convert it to a relative path* and figure things out intelligently

Great, I'll do that then
 

(for example, it will point to a resource under your site even if you
are not deploying to the web server root).  Writing a relative path
yourself can break things if your output structure changes (Nikola
won’t ever do it, you could if you get bored with the defaults or want
to reproduce WP-style /year/month/day/ if you haven’t already**).

No, I turned on PRETTY_URLS, but decided to get rid of the classic WP-style structure. I flattened the hierarchy moving everything to the posts root folder. As the slug is maintained, it'll be fairly easy to add a redirect in Apache/nginx using a regex with a nice HTTP 301. I'm still deciding if I want to keep the year to avoid having hundreds of files in one folder... but I don't write that much. Anyway, it seems easy to move things around and change the structure later. Content in files FTW!!! :)

Speaking of folder hierarchy: in a recent thread there was a discussion about "magic links" vs the :doc: directive (for internal links). Are "magic links" independent of the folder hierarchy? To clarify:

Given the source file /posts/some-post.rst, which slug is "some-post". The magic link "link://slug/some-post" will match it if the file is moved to /posts/foo/bar/some-post.rst later?
 
 

[snip]

I would just use /images/ in this case.  You may want to use
thumbnails one day, and it will just look cleaner in your structure.

Thanks for your input!
 

[Roberto Alsina]

On Wed, Apr 22, 2015 at 4:12 PM, Mariano Draghi <mdr...@gmail.com> wrote:

Speaking of folder hierarchy: in a recent thread there was a discussion about "magic links" vs the :doc: directive (for internal links). Are "magic links" independent of the folder hierarchy? To clarify:

Given the source file /posts/some-post.rst, which slug is "some-post". The magic link "link://slug/some-post" will match it if the file is moved to /posts/foo/bar/some-post.rst later?

As long as the slug is unique: yes.

If it's not unique ... I'd have to see the code ;-)

[Mariano Draghi]

Apparently it warns you and resolves to the first result. Which seems fine.

    def slug_path(self, name, lang):
        """slug path handler"""
        results = [p for p in self.timeline if p.meta('slug') == name]
        if not results:
            utils.LOGGER.warning("Cannot resolve path request for slug: {0}".format(name))
        else:
            if len(results) > 1:
                utils.LOGGER.warning('Ambiguous path request for slug: {0}'.format(name))
            return [_f for _f in results[0].permalink(lang).split('/') if _f]