Posts

Showing posts with the label publishing

Standardizing (a flavor of) Markdown

Update 2014-09-05: Jeff Atwood renames “Standard Markdown” to “Common Markdown” and apologizes to John Gruber. Details: “ Standard Markdown is now Common Markdown ”. On September 3, Jeff Atwood announced a new standardization effort for John Gruber’s Markdown : Standard Markdown . It is amazing how ubiquitous Markdown has become and it’s great that there is now a standard for it. Highlights: The working group comprises representatives from: GitHub, Reddit, Stack Exchange, the open source community. There is a proper specification that also describes a parsing strategy. This should help tremendously with writing a parser that can handle all content that complies with the standard. Given all the incompatible Markdown dialects in existence, that is currently a very difficult task. There are reference implementations in JavaScript and C and a validation test suite. You can try out the reference implementation online. Background: The whole effort more or less started with a blog post b...

Link-friendly content

Have you published a blog post or a GitHub project? This document gives tips for making your content appealing to link to. They are based on things I noticed while collecting material for the JavaScript Weekly email newsletter. The tips should also make your content more appealing to “normal” readers. Cosmetic tips A few superficial measures for a better first impression: Spelling: Make sure your spelling is OK. Alas, the “.js” suffix is used in many variations. When in doubt, look up the name you are referring to. Names that are very often spelled wrong: JavaScript (not Javascript) Ajax (not AJAX): it’s not a real acronym, see the post where the term was invented Node.js or Node (not NodeJS): this one is more tricky, as there are many variations. Starting with a capital N and ending with “.js” seems the most common way to spell it. Links: Don’t use URL shorteners. They don’t let you see where they are poin...

The problem with blogs

I’m a big fan of blogs. After all, I’m writing one, myself. They are the contemporary version of a specialized newspaper. Regularly having new content is exciting and reading blogs is well supported by various apps, thanks to standardized publication formats such as RSS and Atom . The problem However, there is one aspect of blogs that I don’t like: They lead to an obsession with new content. Some blog authors have made it a rule not to update posts that are older than a few weeks. Seeing the date of creation for posts is great (I wish all web pages provided this meta-data), but there is a risk of dismissing good content, simply because it’s old. Redistributing old posts tends to be frowned upon at collaborative news sites such as Reddit or Hacker News. Furthermore, navigating blogs is often difficult, because there is little structure. If you are lucky, posts are well categorized, but even that falls short of proper instructions on where to start reading. Such instructions are especia...

The future of Markdown

The basic idea of Markdown is simple: To create a document, one writes plain text (bullet lists are lines that start with dashes, styles are written **bold** and *italics*, etc.). To display a document, the plain text is converted to HTML. That gives you the best of both worlds: the plain text is to write (much easier than HTML), store and transfer; the rendered HTML is nice to look at. It is amazing how popular Markdown has become: GitHub supports it for files such as readmes and gists; Stack Overflow uses it for comments; Lean Publishing supports no other format for submitting books; many blog engines let you write posts in it; etc. However, Markdown is poorly specified and there are many slightly incompatible dialects. The blog post “ The Future of Markdown ” (by Jeff Atwood for Coding Horror) mentions a proposal by David Greenspan: I think you and I share some concern (horror?) about Markdown's lack of spec and tests. The code is ugly to boot. Extending or customizing Mark...