Content creation is hard enough without adding bad HTML into the mix. Echoing his recent talk at MozCon, we're excited to welcome Ian Lurie from Portent, Inc. on this episode of Whiteboard Friday. Learn how to cut out the cruddy code produced from writing in word processors by adopting Markup and text editors as your go-to writing solution.
Click on the whiteboard image above to open a high-resolution version in a new tab!
Video Transcription
Hey, Moz fans. My name's Ian Lurie. I am the CEO and founder of Portent Inc. I am also the Chief Content Badger there. I'm here today to talk to you about Markdown and how you can use Markdown to avoid all sorts of content and HTML tragedies.
1. The tragedy of content creation
So first thing you've got to understand: The one great tragedy of content creation is HTML. If you're a writer or producer or someone like that and you're creating content, you always run into the problem of trying to get that blog post live or trying to get that page live or whatever else, and you end up with one of four possibilities.- You get bad HTML, because you're trying to write it yourself and you don't know how. I'm one of those people, at least I was until recently.
- You have no HTML at all because you can't do it, and there's no one else to do it, so you end up pasting plain text directly into your word processor.
- You get really slow HTML, because it takes you a long time to punch in all of those tags, or you can find a producer, but it's going to take a long time to find that producer.
- You get really bad HTML, because you write in a word processor, like Word or OpenText or something like that, and you save as HTML, which delivers something that would make any decent HTML programmer pretty much weep tears of blood because it looks so horrible. It adds all this extra stuff. It doesn't render correctly in most browsers, so you don't want to do that either.
So the problem is: How do you create HTML as a writer, without having it interfere with your writing process, right? You don't want to be typing stuff in and all of a sudden you have to stop to write in tags. Without slowing things down because you don't want to have to go back and edit all the HTML either. How do you do that?
2. Yay, markdown!
Well, yay for us, there's this thing called Markdown, and Markdown was created by a developer who runs a blog called Daring Fireball, and I will link to the Markdown Syntax Guide on that site so you can very easily look at it and see it. It is designed to be a really simple way to write in plain text and, with a few simple characters, tag it so that it will turn into really clean, really good HTML.
The great things about Markdown:
- You do write in plain text, so any text editor. You can use one on your phone. You can use one on your laptop. It can be TextEdit, Notepad, anything. I'm going to name a specific text editor in a minute that I think is the best one for you to use. But it could be anything, and you can edit it in anything. It's fully portable.
- That means it's really fast, right? Text editors don't bog down with updates, generally. They don't run into those kinds of problems, so they run really, really fast.
- Text is future-proof. When the day comes that we're no longer reading stuff in text and opening text files, we'll all be communicating directly head-to-head, and we won't worry about all this stuff anyway because you won't need HTML. I'm getting a little bit ahead of myself, but it is future-proof, because 50 years from now you will still be able to open a plain text file.
- It's relatively crash-free. I've always said I've never had a text editor crash. It's true. I've never had one, but as soon as I say that, everybody starts raising their hands and saying, "I had my text editor crash." Maybe it's because you're on Windows. I don't know. I shouldn't say that. But it's relatively crash-free, all right? So it's much more stable than using a word processor.
So you've got all these big advantages. You've still got the problem of how are you going to turn it into what you want it to be?
- Well, Markdown converts to just about anything. If you're willing to go out and study the tools and learn more advanced things like Pandoc, which I'm not going to really talk about today, you can convert Markdown into Word documents. You can convert them into HTML. You can convert them into slides. I've turned them directly into PDFs. You can even do this really fancy typesetting with a piece of software called LaTeX. So there is nothing you can't do with Markdown.
3. Tools & process
How do you do it? Well, the first thing is you need certain tools to fit a process. Like almost any writing process, you write, you preview, and then you convert. If you do that in Microsoft Word, you use Microsoft Word to do your writing, you use Word to do your preview, and then you convert by either saving the file and giving it to someone else, or converting it to PDF or, and please don't do this, converting it to HTML.
If you're doing Markdown...
- You do your writing in any text editor. I will strongly recommend Atom.io, and you'll see why in a minute. And I'll include a link in the text. But just understand Atom.io has many, many advantages. It's really lightweight. It's fast. It's built to handle Markdown, so everything you need is built into it. There's tons of advantages.
- Then you preview it. Well, you can use a website called Dillinger.io. You can use a piece of software on the Mac called Marked 2. But the best way is to just use Atom.io, because it has preview built into it.
- Then you convert it to HTML, and again you can use Atom.io.
I should point out just five to seven days ago, I talked about using a tool called Sublime Text. Sublime Text is excellent for this. I hadn't fully tested Atom.io yet. I have now, and I'm actually switching. I've been using Sublime Text for probably five years now. I'm very sorry Sublime folks, but I'm actually switching to Atom.io, because as a primarily Markdown writer and a very basic text writer, it's very good for me.
4. Making it work
So now it's time to actually get to work, right? So you need to go and download Atom.io. Install it. It's free, by the way. It costs nothing. Did I mention free? Like zero dollars.
- You start writing. Usually, as soon as I start writing, I...
- Save my file and then I save it a lot. And again, because it's a text editor, saving only takes a couple seconds, so it's much, much easier. You save it whatever you want your file name to be with a .md on the end. The .md tells Atom.io and, by the way, almost any other Markdown-literate tool out there, that this is a Markdown file so that when you open it, it will highlight your syntax correctly. I'm going to get to syntax in a minute, but it will highlight and differentiate between the markup and the actual words and sentences that you're writing. So it's very easy to spot that you formatted something as a heading, for example.
- You do more writing. You keep saving. Always save it. They don't crash. I've never had them crash, but apparently other people have.
- Then you go to Packages in the menu, click Markdown Preview and you click TogglePreview. Now, you can do that at the very start, and then what you'll have is two parallel panes where in one pane you're doing your writing, and in the other one it's showing you exactly how the page is going to look. Or you can just do it at the end. I do it at the end because it's distracting. I don't like seeing how it's going to look at the same time.
- You right-click in that preview. You click Copy HTML, and you'll have flawless HTML. I mean flawless. It even converts little single quotes and double quotes to the correct smart quote, so double left-hand, double right-hand curly quotes, whatever.
5. Syntax
Syntax is really simple. Again, I'm going to link to the syntax. I'm not going to give you the complete course on the syntax. The truth is this is 50% of what you'll probably need right here.
But just as an example, if you want to do a level one heading, you do a single pound sign or a hash, a space, and then whatever your text is. When you convert it to HTML, it will automatically become H1, heading one, closing H1. Same thing with H2. You just do two hashes. You can imagine what you do for H3. It's three hashes.
Paragraphs are created automatically. So if you write some text and you hit Enter or return twice, you'll get a clean paragraph. If you want, by the way, for this to be a hard break instead, then you just do two spaces and then return, and it'll put a BR there instead of a paragraph.
Lists become lists, and this is one of the toughest things for writers. It was always the thing that slows me down the most is lists are pretty complicated in HTML. Well, here, you just go one, two, three, just normally your text, and when you save it and convert it, it's going to become order list, list item, list item, list item, closing order list. It's that easy. If you want to do a bulleted list, you just use asterisks instead. It'll do the same thing.
Links, I got really excited so I had to add this up here. Links are also really simple and in fact, again, super simplified in Markdown. What you've got here is you put your text in brackets, then in parentheses you put your web address. It will convert to a full link with the text as your proper link text. You can do the same thing with images. All you do is add an exclamation mark at the start.
So Markdown really lets you take your skills as a writer, focus on those skills, write really well, and convert it to equally good HTML. Then you've got HTML that's ready to be pasted into WordPress or whatever other system you want, or just to be used as a separate page.
That's it. I hope you have fun working with Markdown, and please leave any questions you have in the comments and I will get to them and answer them as quickly as I can. Thanks.
Hi Ian, nice contribution!
Honestly I don't think basic HTML is that hard to learn and code, especially the kind of code that Markdown does for you. However I agree that it's ridiculously fast and easy to use, and I love to write with it.
For taking notes and writing using Markdown, I'd recommend Laverna, which can sync texts between devices and has a live preview. But I don't know yet any nice Markdown plugin for writing posts directly in my Wordpress. Do you already know anyone?
Hi Angel,
I hear ya. I've been doing HTML for a long time. When I'm writing I prefer Markdown because of speed (as you said) and because I don't have to hand-convert my writing to HTML.
Laverna looks cool. I have to try that.
I know a few Markdown plugins, but I haven't had much luck. Plus, they only work for Wordpress. I prefer to convert to HTML on my computer and then upload it.
Markdown is supported by a fairly common Wordpress plugin: Jetpack
Jetpack utilizes Markdown Extra, which provides support for features which aren’t included in standard Markdown; such as tables, inline HTML, code blocks and more.
Oh, I've to take a look on that, thank you Brendon!
I haven't used jetpack for years, we'll have to give it another chance. Thank you Brendon
This is very interesting and I can see the benefit here. Just curious about one aspect - Links.
I checked out Daring Fireball's site and saw a few examples but didn't see anything referencing link attributes. While perfect for the regular user/blogger, I'm interested to see how SEOs can add Ga onclick tracking, rels, or targets on this.
That's much more complicated. Markdown can create clean, basic HTML. If you want to add that stuff, I suggest doing so after you've converted to HTML.
@robteee There are multiple "flavors" of markdown, so I'm not sure that Ian's comment about it being much more complicated is 100% accurate since it depends on your flavor.
You can definitely add attributes to anchors, especially in the interest of accessibility (e.g. the "title" attribute), which is supported by GFM (GitHub Flavored Markdown, arguably the most popular flavor). As far as other link attributes like class or data attributes, adding that to markdown can be done but would kind of defeat the purpose. Markdown is for content (think "body" copy), so it's very unlikely that you need a large amount of CSS differentiation, and that's a muddling of separation of concerns as well...
Note that you can also create reference links very easily in body copy that go to footnotes at the bottom of a page with almost every markdown parser or static site generator. Markdown also consolidating your efforts by allowing you to create pointers to links that you might use more than once in a page.
For example, in your markdown copy:
This is a [link to Google][google]. Go and check out [Google's website][google]. I really love [google][].
Then near the bottom of your body copy, just add the following:
[google]: https://www.google.com "The world's most popular Internet search engine."
And all the above anchors will be rendered accordingly, with the title attribute as well. HTH.
Exactly what I needed.
Thanks to you Peter now I am sure I am gonna learn at least basic HTML
I've wanted to like Markdown for years, but I just can't. For a standard blog post, creating an html template to start with every time seems to work well for me. I use Sublime and Emacs, mostly, and also could never really like Atom. Markdown just feels like something that best serves tech bloggers using static blogging engines, and they all look the same...like a Git Hub README.md file.
Still, this is a very comprehensive well-written article for those who want to use Markdown. The only recommendation I would make is just skip the text editor if all you're doing is Markdown, and use something like QOwnnotes, and use it to keep all your blogging notes, drafts, and published files structured and organized.
Emacs Org Mode has intrigued me for years...
Ian, Nice to see you here after a long time :)
I’m sorry but I disagree with you on this. I don't prefer because-
Agree, Markdown is easier and simple to write, but only for limited use cases.
BTW Ian, Please correct your anchor text "Dillinger.io" in point #3-Tools & process, when I clicked, 404 page came up.
Hi Kuldeep,
I hear you. Markdown gets a lot more right than I do, as a writer, when I'm trying to generate basic HTML. Can you point out where you see Markdown generate something other than clean HTML?
The other issues you're describing may be your text editor. The Markdown language has always done fine for me with copy and paste, etc.
Thanks!
Ian
Thanks for the heads up about the broken link, Kuldeep -- all fixed! :)
Ian - given that you're writing this on Moz.com, maybe you could say a little bit about how you handle page metadata in the MD->HTML workflow? We still need description, page title, opengraph properties (probably from your generator), etc., and MD really only addresses body content.
OK, for that, I add Jekyll: https://jekyllrb.com/. When you write pages and posts, add something like this at the top (it'll vary depending on the template):
---
title: Your title here
description: Description here
---
Then Jekyll will convert it all to HTML.
This is probably more complicated than necessary. It's my preferred method. The other option, of course, is to add the tags later on, but that demonstrates insufficient nerd-fu for me.
Jekyll is really amazing software. Note the above is actually embedded YAML inside of a markdown file. If you're looking for an immediate feedback loop (i.e., you type, you save, your browser refreshes automagically), I'd recommend checking out Hugo (https://gohugo.io). Full disclosure, I'm (but a small) part of the project.
A key advantage of the above approach that uses markdown files with embedded metadata (commonly called "front matter" in the static site generator world) is that it's the semi-de facto standard for creating content across almost all static generators. Makes content extremely portable...
For this, Hugo is also a great static site generator, with the huge advantage of only requiring a single executable file on your computer to use it. Unlike something like Jekyll that requires a bit more of an installation process and dependency management.
Hugo is also insanely fast when building sites. Usually in the 10s or 100s of milliseconds. This makes full site live preview possible.
Thanks for this post, it was definitely interesting.
However, I feel this just isn't useful and relevant for me anymore. I have very few issues with copying and pasting from word into a wysiwyg in Wordpress or Drupal. Especially if they are set up correctly to begin with.
This would have been great for me a few years ago when programs weren't as good at understanding different mark up and stripping out useless tags.
I also find when writing I like to clearly see the headers as I am writing so I can get a real feel of the format. I just don't get this same flow with writing in a text editor.
But if this is working for you awesome!
Thanks for exploring this topic Ian!
I would just extend this little bit.
Markdown is created from John Gruber. And with little help from Aaron Swartz. First guy is well known from it's site "Daring Fireball" and was one of designers of BB-Edit/TextWrangler. Aaron is one of RSS creators, early developer of Reddit.
And MD getting popular from Reddit, GitHub and WordPress (using JetPack plugin).
Hi Peter, It's sounds good. Thanks for this extra dose :)
Thanks Peter. Only had so many minutes :)
I did link to his site for the syntax and talk him and Markdown up everywhere I go.
Exactly what I needed.
Thanks to you Peter now I am sure I am gonna learn at least basic HTML
Basic HTML is not hard to learn and code, and possibilities are huge. It is possible to learn it in a few hours and it worths every minute.
I may be reaching here, but with the overwhelming amount of people who use regular software (google docs, MS Word, etc) and paste the text, shouldn't Google be used to this by now and be able to decipher it correctly (and easily)? Surely they haven't been hurting and penalizing sites all along for some not-perfect html. Some massive, successful sites are still doing this and don't seem to be affected.
I guess, but to be honest, if you're building web sites and writing blog posts, you need to be able to do it without generating all the bloat of a program like MS Word. This isn't really about Google crawling content. It's about browser rendering speed, transfer time and code that works across many devices and viewers.
And about web semantics, and portability of content, and future redesigns (especially w/r/t typography), and avoiding product lock-in...
Not 100% related, but note that there is a Google Doc extension that will convert your Google docs to Markdown:
https://chrome.google.com/webstore/detail/export-a...
If anyone is interested, ping me. There are plenty of open source tools that make the Word-PDF-Markdown-HTML workflow much easier.
One of simple and best effective tool I use is stackedit(dot)io . Easy,fast and superb if you have to use markdown and recieve clean html.
Other benefit is improvement of readability of content .It is also helpful to convert MS word docs to quickly convert in html
I feel really lucky that I was learning HTML at school. It makes so many things easier.
Excellent post Ian !!
Many things to keep in mind for my project I did not know.
Thank you!
Dear Ian Lurie,
I would hereby, like to request a kind of new space which is not yet discussed by anyone in details with guidelines and expert opinion.
INCREASE IN NUMBER OF USERS!
Due to increasing user base of Mobile chatting tools, like Whatsapp and Hike Messenger, GIF is the new tool to spread your Brand and also works as indirect SEO tool.
HITTING THE RIGHT TARGET AUDIENCE
If an interesting GIF animation is shared on Groups on Whatsapp, it can go viral and can reach directly to the potential customer's inbox.
ORGANIC SEO?
Yes, this can also severely result in Organic SEO as GIFs cannot have urls or backlinks, so obviously people will Google it. But to create an interesting and entertaining GIF which is almost impossible to ignore for sharing, is a challenge.
THE CHALLENGE
GIF allows only few (mostly 5 to 10) seconds to deliver the whole message from beginning till end. Less time means more concentrated content and no garbage. To create such a concentrated content with indulging content is a matter of art and expertise.
NICHE SEGMENT
It would be great if someone can put some lights on that as it is mostly untapped topic on any other blogs discussing about SEO. We on behalf of Midnightcake can give a good example of case study who got almost 15,000 visitors in 2 days after a GIF went viral across the country and some parts of overseas too. That increased the sales of midnightcake exponentially. For reference you can check few such GIFs on GIPHY created by Midnightcake team.
Looking forward for expert opinion on this topic.
Thanks and Cheers !
thanks for share, I always learn something new on this blog
Is this really easier than wordpress? I could have definitely used this in my pre-wp days, but composing in the semi-wysiwyg wp editor has been fairly simple. What advantages do you see in starting with atom.io? (not challenging, just curious)
Thanks!
This is a really big question. Not to get too semantic, but you'd have to define "easier." Keep in mind that text files can be opened by, quite literally, every computer on the planet. You can also edit and create content offline. You also never have to worry about exporting your content and metadata since you've created a smart separation layer between your content and CMS and all the crazy (and trust me, it is crazy) frontend code required to create a WYSIWYG and non-technical-user-friendly GUI like that used in Wordpress and others.
Your question is also tough to answer because it's comparing a CMS layer with a syntax. (Sorry if that only adds confusion!).
You might also take a look at VSCode as an editor. It opens a bit more quickly and has a lot of support for Markdown and Live Preview. I used Atom for a while and even wrote a fairly nice extension for it, but I use VSCode exclusively now.
If you want to use Markdown to create more advanced documents or books, check out Madoko. There is an online editor that can sync with your repositories (Dropbox and GitHub) and you can also run madoko-local to use the editor on your PC and edit local files with it. Madoko makes it easy to output documents to HTML and PDF through a LaTeX engine.
Another advanced markdown format is AsciiDoc. It is also a very nice document system with extensions for Atom.io (one of them I helped to make).
The biggest difference between Madoko and AsciiDoc is that Madoko uses a LaTeX engine behind the scenes for PDF creation and AsciiDoc uses DocBook.
Ian, just as an FYI--and of course I don't take offense that you left ST3--but there is a markdown preview for your old editor as well:
https://packagecontrol.io/packages/Markdown%20Prev...
What about the W3C Markup validator?? (one of the most officials to check this) is the one i check in my sites to see the markup is correct (sorry i have not see it in the article).
Thanks for the contribution.
I've been experiencing some issues in my web with google spider and now i think is because some erros on my links. I will have to check every point you wrote and see if it improves. Hope i can give some use to the tools you wrote.