Rel4tion-Wiki/editing/help/using-images.mdwn

# Intro

Some file types are not handled well by certain version control systems. Many
version control systems aren't made to handle large or binary files, and don't
know how to handle their versions other than keep each version in the history.
For some file types, even if not large or text based, version control in the
wiki doesn't make much sense, and they may be treated like binary files.

One such kind of files is __images__. There are two kinds of image encoding:

1. Vector graphics
2. Raster graphics

Vector graphics are usually published as text-based SVG files. Git can handle
them and display changes, but since Partager is not an image editing project,
the development of the SVGs doesn't happen here and the version control isn't
very useful. If a file is changed, there's a good chance it's a big change with
a long diff, or even a whole new image, not based on the previous one.

Raster graphics are binary data, usually compressed. JPG is popular for
pictures taken by a camera, and PNG is popular for computer-generated images.

# Formats

Always use free open formats. The preferred formats are:

- SVG for vector graphics
- PNG for computer-generated raster images
- JPG for camera-made pictures
- Dia/ODG/dot for diagrams
- For image sources, you can upload the XCF source files Gimp uses

# Where to Upload

When uploading a single small image, pushing it to git is fine. Diagrams can go
to git too, since their development usually happens in the wiki. Otherwise,
prefer to store them outside version control.

This wiki uses an [underlay](https://ikiwiki.info/plugins/underlay) which can be
accessed via HTTP and FTP. The clearnet address is <http://files.partager.null>.
The *wiki* folder is the underlay.

__Note:__ Currently there is no upload access yet. Only public read access. If
you want to upload something to the underlay, send it to me and I'll put it
there. You don't have to wait - just put a link on the relevant pages as usual,
and the links will be dead until I upload the file - when I do, they will start
working. This way you won't have to wait for me. Another option is to store
the image somewhere else for now, e.g. a MediaGoblin instance.

[[TODO|TODO/OPEN]] enable HTTP/S-with-password upload and/or SFTP upload and/or
FTP/S-with-password and/or Kerberos or something.

In the underlay, put the image in the *images* folder, e.g.
*files.partager.null/wiki/images/hello.svg*, or in a subfolder corresponding to
the section which uses it. For example, if an image is uploaded to be used as an
attachment to the page *tutorials/gnupg.mdwn*, you can put it at
*wiki/tutorials/gnupg/image.png* and then simply use `\[[image.png]]` in the
page (or the [[ikiwiki/directive/img]] plugin).

# How to Embed in a Page

A [[ikiwiki/WikiLink]] to an image embeds it in full-size, e.g.

	\[[image.png]]

For more flexibility and options, you can use the [[ikiwiki/directive/img]]
directive, e.g.

	\[[!img image.png size=200x600]]

If you want to center the image horizontally, set the class to "center", e.g.

	\[[!img image.png size=200x600 class="center"]]

For other alignments to work, e.g. right alignment or vertical alignment, the
[[CSS]] needs to be edited. You can e.g. add an *img.right* class in a similar
way to the *img.center* class defined at the bottom of *local.css*.