A quick introduction to Markdown

We store our articles in a simple plain-text format called Markdown. We chose Markdown because it’s human-readable and can be edited without special proprietary software, thereby reducing the risk of technological obsolescence in the future. Once we have a Markdown file, we can use it to easily generate a range of other document formats, like web pages (HTML), printable articles (PDF), or e-books (EPUB).

Here are some quick guidelines to use when converting scanned images to Markdown.

Paragraphs

Line breaks and spacing don’t matter. Just separate paragraphs with at least one blank line:

Original image Markdown

Kandidatoj anoncu sin kiel eble plej frue.

La komitato devos fini siajn rekomendojn kaj sendi ilin al la prezidanto.

Kandidatoj anoncu sin
kiel eble plej frue.

La komitato devos fini siajn rekomendojn kaj sendi ilin al la prezidanto.

Line breaks with hyphens

Printed articles often split words across lines using hyphens. Remove the hyphens and re-join the split words. You can re-flow the lines as you like; line-breaks don’t matter.

Original image Markdown

The software allows you to create graph-
ics quickly and easily. No strong com-
puter background is required.

The software allows you to create graphics quickly and easily. No strong computer background is required.

Bold and italics

Bracket the text with double asterisks for bold, single underscores for italic.

Original image Markdown

Jen dikaj (“bold”) literoj, kaj jen kursivaj (“italic”).

Jen **dikaj** ("bold") literoj kaj jen _kursivaj_ ("italic").

Surnames / Small Caps

Surnames sometimes appear in all capitals (or “small” capitals). Capitalize just the first letter in Markdown, but surround the word with plus-signs:

Original image Markdown

Membro Joe Ŝmo raportas, ke ...

Membro Joe +Ŝmo+ raportas, ke …

Bulleted (“unordered”) lists

Use asterisks as bullets for list items. If you wrap lines in an item, indent subsequent lines to make them line up with the text of the first.

Original image Markdown
  • Here's the very first item.
  • Another item.
  • Yet another item.
* Here's the very
  first item.
* Another item.
* Yet another item.

Special punctuation

Some punctuation can be difficult to type. Luckily, you can use simple equivalents: three hyphens for a long (“em”) dash; two for a short (“en”) dash. You can also replace the fancy opening and closing quotes and apostrophes with the “straight” versions found on US keyboards.

Original image Markdown
  • “ ” ‘ ’
* ‐‐‐
* ‐‐
* " " ' '

Photos/Figures

Just ignore these; the editor will add them later. If a photo or figure has a caption, however, add the text at the end of the article, in a separate paragraph.



An example

Here’s an example using most of the tips above. Note that we’ve removed the hyphens used for breaking lines in print. They aren’t needed in Markdown.

Original image Markdown
About a year ago, a new program called _HyperCard_ was published by Apple Computer Co. Since that time _HyperCard_ has quickly become one of the most talked-about computer applications of the last few years.

Simply put, _HyperCard_ is software that allows people to create applications quickly and easily, complete with graphics and even animation without any strong computer programming background. The concept or metaphor is that of the card---the index card or Rolodex. A completed program is called a stack. _Hypercard_ stacks are so easy to build and lend themselves so well to educational uses, that it's not surprising that a stack for learning Esperanto has already appeared. It's Michael Urban's Esperanto Course. The program requires, at a minimum, a Macintosh computer (with at least 1 megabyte of RAM) and _HyperCard._ It's also nice to have _MacinTalk_, a speech synthesis driver, because then the program can also "talk," helping a beginner learn the Esperanto pronunciation.

The opening "card" of the Esperanto "stack"