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- |
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. |
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 that uses the tips above.
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" |