Introduction

Content for Kerb is stored as Markdown formatted-plain text files and organised by folder.

What is Markdown?

Markdown is a plain-text syntax that records text formatting visually, such as *italics*. It is often used in web-based commenting system and software documentation. Markdown was designed as a way for web authors to write HTML without the comparatively bulky distractions of HTML tags. If interested about this background, you can read more here.

How do I write Markdown?

A general introduction to the syntax can be found here.

Any plain-text application, e.g. Notepad or Textedit can be used to write Markdown. Code editors or Markdown-specific applications will make writing Markdown easier as they will generally have a nicer writing UI, can highlight the Markdown syntax, and can show a preview of the resulting HTML.

Typora is a good and free cross-platform Markdown editor. It works more like Microsoft Word in that it hides the Markdown syntax behind a graphic interface and by default shows the resulting HTML. If using it you will want to toggle into "source code mode" to check how your syntax looks.

Another option is to use Visual Studio Code which is also cross-platform and free. It will let you show the source and preview modes side-by-side which can make learning and checking Markdown easier.

How do I translate Kerb Articles to Markdown

• If you have the article as a Word document, this website should do most of the conversion
• If you have the article as a PDF, you will need to copy/paste the text over.

Remember that Markdown is a plain text format. If you copy text with formatting (e.g. italics) from a PDF, you will need to recreate that formatting in Markdown. Footnote markers will also be copied across directly and need to be convered into Markdown footnotes.

Content Structure

Rather than using a database to store the relationships between content, the Kerb site matches up files by their name. That means that those names need to follow a particular standard and be used consistently. There are three main types of file that correspond with three primary types of data:

1. Articles, that live in the _articles folder.
2. Contributors, that live in the _contributors folder. This includes both the editors of each edition and the authors of each article
3. Editions, that live in the _editions folder

Article files and Contributor files always end in .md and always use hyphens instead of spaces. This is so that they can be looked up in urls — spaces are not allowed in URLs.

Metadata

Each type of Markdown content has a "header" section that specifies it's metadata. This looks like a set of lines such as "title: ’Augmenting XYZRGB’" sandwhiched between two sets of ---.

Each of these lines must be filled out and the use of colons/single-quotes should be closely followed. It is easiest to start by copying over this section from another author/contributor file and replacing the information.

Importantly, and counter-intuitively, the listing of authors for each article should list them in their hyphenated form; not their plain English form. That is to say, that line should read authors: [’John-Smith’, ’Jane-Smith’] and not authors: [’John Smith’, ’Jane Smith’]. Multiple authors should be comma-separated inside the square brackets, with the commas outside the single quotes.

Please ensure that you always create corresponding author files for all of the authors in each article. Ideally the 'main' section of the Markdown file would list their author bio — as found in the back of each Kerb — but don't worry if that information is not available.

Working with Images

Images are stored in the public folder and its articles sub folder. They are then organised into folders whose name matches the hyphenated name of the article file public/articles/the-agency-of-mapping/01.jpg. The image files themselves can be named whatever, but they must be saved as either PNG or 100 percent quality JPG files.

When referring to them in Markdown, you just need to refer to their location without the "public" prefix. E.g.

![Image showing mappa mundi of Medieval Europe](/articles/the-agency-of-mapping/01.jpg)

The alt tag, i.e. the "Image showing a mappa mundi ..." should be present and should be distinct to the figure caption. It's purpose is primarily to describe what the image shows to people without vision.

Extracting images

To properly extract images from PDFs at high resolution, you should open the PDF in Adobe Illustrator and unembed the image. This will let you save the file. To get this option you will likely need to release all clipping masks and then isolate the image itself. The resulting embed may be a PSD or a TIFF and will need to be converted. When converting keep the image at it's original dimensions/resolution, even if that is very high or creates a very large size. The web system will handle re-compressing the image as needed.