How to Set Up & Use Atom as a Markdown Editor

• Ian Lurie
• NOV 20 2017

In my Mozcon presentation this year, I talked about Markdown. I’ve had a few people ask about my toolset, so here’s how I install and use Atom to write Markdown. Enjoy.

Atom is fast becoming my new favorite text editor. It handles Markdown beautifully, is great for HTML, runs faster than stink, and has great community support. It’s also free.

Here’s how you install Atom and set it up as a full-featured Markdown editor:

Note: I’m doing this all on a Mac. I’ve included Windows commands where relevant. I hope.

Installing Atom

Easy-peasy:

1. Visit Atom.io
2. Click Download
3. Install it
4. When it opens the first time, you’ll get all manner of welcome screens, etc. Close them
5. Click File >> New File
6. If you don’t want your lines going all the way across the screen, click View >> Toggle Soft Wrap
7. You’re good to go. Start typing

If you want to download a specific version, because you’re a nerd, visit the Github repository and take your pick.

Working With Project Folders

If I’m working on a multiple-document project, or writing some awful code, I like to see all the relevant files in one place. That way, I can quickly scan for related images, content, or scripts, without interrupting my flow. Atom lets me do just that:

To view an entire folder:

1. Click File >> Open
2. Navigate to the folder you want to open
3. Instead of clicking a file, click Open

Atom then opens the desired folder, listing all files contained in it:

Now you can jump between files without clicking File >> Open.

You can also add other folders to a project. I’m not going to talk about that here.

Setting up for Markdown

Of course, I’m a Markdown fanatic. You should be, too.

Atom is a kick-ass Markdown writing, editing, preview, and conversion tool, all in one. You have to do a little setup, but it’s easy.

Open Atom’s Package Manager

Atom has thousands of packages—think of them as plugins—available at https://atom.io/packages. You can install them using the package manager:

1. On OS X, click Atom >> Preferences.
2. Click Packages

If you’re on Windows, click Packages >> Settings View >> Open.

You’ll see something like this:

You’re ready to install the packages you need for Markdown.

Install Markdown Packages

Atom Markdown packages number in the dozens. But I find I only need three:

language-markdown
markdown-writer
markdown-preview

They add nifty things like Markdown syntax highlighting:

And autonumbered lists:

And let you preview your document without leaving Atom:

To install:

1. Open the Package Manager
2. Open Settings
3. Click Install (on OS X) or Open (on Windows)
4. Search for the package you want. In this case, type “Markdown” into the search box
5. Choose the packages and click Install

Markdown installs the package. You’re good to go.

Setting Up a Document, My Way

It’s time to start writing. Here’s how I do it:

If You Are Writing a Simple Document

If you’re writing a single document that won’t include other files like images:

1. Start Atom
2. Create a new file
3. Save the file as FILENAME.md, where FILENAME is whatever you name the file. The .md extension tells Atom this is a Markdown file. Atom will apply the right packages and syntax highlighting

If Your Project Will Contain Multiple Files

If you are writing a multiple-file document—like a multiple-chapter book—or will be including other files like images, start with a folder:

1. Create a new folder on your computer. This folder will hold all of your files
2. Start Atom
3. Open the folder in which your document currently lives or will live
4. Create and save a new file as above

Opening Preview

I use markdown-preview so I can see how my document looks without leaving Atom:

To use it, you need to toggle Preview. There are keyboard shortcuts, but the easiest way is clicking Packages >> Markdown Preview >> Toggle Preview:

Converting Markdown to HTML

For delivery, you probably need to convert Markdown to something else:

1. Toggle markdown-preview so that you can see the document preview
2. Right-click in any blank area of the preview. Otherwise, Atom will copy the word or image instead of the entire document
3. Click Copy As HTML…
4. Paste the result wherever you need it

That’s it. You’ve got HTML.

Tons of Other Features

Atom lets you install lots of other packages, customize your theme, change fonts, etc. etc. and so forth. Feel free to explore. My only caution: Like any software, the more packages/plugins you add, the slower and more prone to errors Atom gets. Be somewhat picky.

So Simple

Compare this whole install process to, say, installing Microsoft Word. Which takes longer?

Uh-huh. That’s what I thought. And that’s why I love working with Atom and Markdown. It’s simple. Give it a shot.

If you have questions or suggestions, leave a comment.