How to Set Up & Use Atom as a Markdown Editor
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.
- Visit Atom.io
- Click Download
- Install it
- When it opens the first time, you’ll get all manner of welcome screens, etc. Close them
- Click File >> New File
- If you don’t want your lines going all the way across the screen, click View >> Toggle Soft Wrap
- 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:
- Click File >> Open
- Navigate to the folder you want to open
- 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:
- On OS X, click Atom >> Preferences.
- 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:
They add nifty things like Markdown syntax highlighting:
And autonumbered lists:
And let you preview your document without leaving Atom:
- Open the Package Manager
- Open Settings
- Click Install (on OS X) or Open (on Windows)
- Search for the package you want. In this case, type “Markdown” into the search box
- 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:
- Start Atom
- Create a new file
- Save the file as
FILENAME.md, where FILENAME is whatever you name the file. The
.mdextension 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:
- Create a new folder on your computer. This folder will hold all of your files
- Start Atom
- Open the folder in which your document currently lives or will live
- Create and save a new file as above
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:
markdown-previewso that you can see the document preview
- Right-click in any blank area of the preview. Otherwise, Atom will copy the word or image instead of the entire document
- Click Copy As HTML…
- 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.
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.