LXer now speaks Markdown

What changed

Every place on LXer where you write more than a line now has a Markdown editor:

• submitting a story to the newswire
• starting a forum topic, replying to one, and the Quote link on a post
• private mail between members, including replies and quotes
• editing your own posts

You type plain text, and a few marks such as asterisks, pound signs and backticks say how it should look. A toolbar above the text box inserts the marks for you, so you never have to remember them. Two buttons are worth knowing about: the eye shows the post exactly as it will be published, and the split-screen button shows your text and the result side by side as you type.

The first reactions from members have been positive. Thank you to everyone who tried it early and told us what worked and what did not.

Writing a post

Here is a short forum post as you would type it:

## Why I moved my server to Debian

Three reasons, in order of **importance**:

1. Stable releases
2. The `apt` tools
3. The community

> Debian: the universal operating system.

More on the [Debian website](https://www.debian.org/).

That gives you a heading, bold text, a numbered list, a bit of code, a quotation and a link, and the text is still easy to read before it is formatted. That is the whole idea of Markdown.

The marks you will use most often:

A web address on its own line becomes a link by itself. Three backticks on their own lines around a block of text keep it exactly as typed, which is what you want for commands, configuration files and log output.

One thing works differently on LXer than on many other Markdown sites: pressing Enter starts a new line. A blank line starts a new paragraph. We heard early on that people expected their line breaks to stay where they put them, so they do.

Tables, footnotes and math

Tables are drawn with | characters, and the columns do not need to line up. The table above was typed that way.

Footnotes keep a source or an aside out of the way of the text.¹ They are collected at the end of the post.

This is a Linux site, and some of our readers write about algorithms, signal processing and cryptography, so the editor also understands LaTeX math. Put a formula between dollar signs for inline math, such as $E = mc^2$, which gives E = mc^2, or between double dollar signs on their own lines for a displayed formula:

$$
\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
$$

which comes out as

\sum_{k=1}^{n} k = \frac{n(n+1)}{2}

Prices are safe: "it costs $5 or $10" stays plain text. A formula has to start right after its opening dollar sign and end right before its closing one, and a dollar sign followed directly by a digit never closes a formula.

Pictures, links and safety

Editors can place pictures in stories. In members' posts, an image is shown as a link to the picture instead, so nobody can slip a tracking pixel or a hotlinked image into a forum thread. Links in members' posts carry the usual nofollow marking, which takes the reward out of link spam.

Anything that looks like HTML is shown exactly as typed and never run. If you want to explain the <script> tag, you can simply write it.

Older posts

Two decades of LXer posts were written with BBCode-style tags and bits of HTML. They look exactly as they always did. When you edit an old post, it stays in its old format; only new posts are Markdown.

Help is one click away

Every editor has a ? button on its toolbar, and a "Formatting help" link below it. Both open a cheat sheet with examples of everything above, shown side by side as you type them and as they come out. The cheat sheet is also its own page: Markdown help.

Sixty years of writing in plain text

Markdown did not come out of nowhere. People have been putting formatting instructions into plain text for as long as computers have printed documents, and almost every idea in Markdown was tried somewhere first.

RUNOFF and roff: commands in the margin

In 1964 Jerome Saltzer wrote RUNOFF for CTSS, the time-sharing system at MIT. A line that started with a period was a command: .center, .skip, .page. Everything else was text to be filled and justified.

RUNOFF's descendant roff had an important role in the history of Unix. Around 1970, the Bell Labs team behind Unix got a PDP-11 by promising the patent department a system for preparing patent applications. The text formatter that ran on it was roff. Joe Ossanna's nroff and troff followed, for terminals and for the phototypesetter, and the Unix manual itself was typeset with them.

You still use roff every day. Type man ls on any Linux system and groff, the GNU version written by James Clark, formats the page. Manual pages are written in commands like .TH and .SH that RUNOFF users in 1964 would recognize.

TeX and LaTeX: where our dollar signs come from

In the late 1970s Donald Knuth was unhappy with how the new edition of The Art of Computer Programming was being typeset, so he wrote his own typesetting system, TeX. Leslie Lamport's LaTeX macros made it practical for everyday papers in the early 1980s, and it is still the standard in mathematics and physics.

TeX put math between dollar signs. That is why $x^2$ means math on LXer today, as it does on GitHub, in Jupyter notebooks and in countless other places.

GML, SGML and HTML: tags

At IBM in 1969, Charles Goldfarb, Edward Mosher and Raymond Lorie designed the Generalized Markup Language. GML described what a piece of text was, a heading or a list item, not how it should look. GML grew into SGML, an ISO standard in 1986, and in 1991 Tim Berners-Lee at CERN used SGML's angle-bracket tags for a small language called HTML.

HTML is precise, but it is tiring to write by hand, and letting visitors type it into a web form is dangerous. That problem shaped everything that came next.

Email, setext, wikis and BBCode

Meanwhile, people writing email and Usenet posts had settled on their own conventions: *stars* for emphasis, _underscores_ for titles, and > in front of quoted lines. Nobody designed them; they simply worked in a plain-text world.

Around 1992 Ian Feldman created setext for the TidBITS newsletter, which was distributed as plain text. A title was underlined with a row of = or - characters, and Markdown still accepts headings written that way.

In 1995 Ward Cunningham opened the first wiki, the WikiWikiWeb, where anyone could edit any page in their browser. Wiki markup used doubled apostrophes for italics and ran words together into links. Wikipedia's markup descends from it.

Web forums needed a way to let visitors format posts without letting them write raw HTML. In 1998 the Ultimate Bulletin Board introduced BBCode: [b]bold[/b], [i]italic[/i], [url]...[/url]. It looked like HTML with square brackets, and the forum software only had to understand a small, safe set of tags. BBCode spread to phpBB, vBulletin and countless other forums, and it is what most of LXer's own archive is written in.

2002: Textile, reStructuredText and atx

By 2002 several people were trying to design a markup that was easy to type and easy to read. Dean Allen released Textile for his blogging tool. David Goodger's reStructuredText became the documentation format of the Python world. The Linux kernel also adopted it: since version 4.8 in 2016, the kernel's documentation has been written in reStructuredText and built with Sphinx.

That same year Aaron Swartz published atx, a small format with headings marked by # at the start of the line.

2004: Markdown

In 2004 John Gruber released Markdown, a Perl script that turned plain text into HTML, with Aaron Swartz as his main collaborator on the syntax. The name was a play on "markup". The guiding rule was set out in Gruber's syntax description:

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions.

Markdown borrowed openly from what came before. Gruber's own documentation calls the two heading styles "atx-style" and "Setext-style". The email conventions for emphasis and quoting came along almost unchanged.

Aaron Swartz had already helped write the RSS 1.0 specification as a teenager. He went on to co-found Reddit and to campaign for an open Internet, and he died in January 2013 at the age of 26.

Success, and a specification

Markdown spread from blogs to Stack Overflow, which adopted it in 2008, and then to GitHub, where a README.md file became the front page of nearly every free software project. Today it is in chat programs, note-taking apps, issue trackers and documentation sites.

Success brought a problem. Gruber's description was short and friendly, but it left many cases open. What happens to a list right after a paragraph? How many spaces indent a sub-list? Every program answered differently. John MacFarlane, a philosophy professor at UC Berkeley and the author of the document converter Pandoc, built a tool called Babelmark that sends the same text to dozens of Markdown programs. It showed how often they disagreed.

In 2014 MacFarlane, Jeff Atwood of Stack Overflow and others published a precise specification with hundreds of test cases. They first called it "Standard Markdown". Gruber objected to the name, so they renamed it CommonMark. In 2017 GitHub based its own dialect, GitHub Flavored Markdown, on CommonMark and added tables, strikethrough and automatic links. GitHub added $-delimited math in 2022.

LXer follows the same path: CommonMark, plus GitHub's tables, strikethrough and automatic links, plus footnotes and math.

Under the hood

For readers who like to know what runs their software:

• league/commonmark, a PHP library maintained by The PHP League (BSD license), turns Markdown into HTML on the server, following CommonMark and GitHub Flavored Markdown.
• KaTeX, written at Khan Academy (MIT license), draws the math in your browser. It is only loaded on pages that contain a formula.
• EasyMDE (MIT license) provides the editor and its toolbar, with icons from Font Awesome.
• The preview is rendered by the same server code as the published post, so what you see is what you get.
• Your text is stored as you typed it, so when you edit a post you get back exactly what you wrote.
• Every file is served from lxer.com. There are no outside content networks and no trackers.

Tell us what you think

The best way to learn Markdown is to try it: open the forums, start a reply, and press the eye button to see the result before you post. If something does not look the way you expected, or there is a feature you miss, post a comment below. This comment box uses Markdown too.