{"id":352959,"date":"2021-10-06T07:22:18","date_gmt":"2021-10-06T14:22:18","guid":{"rendered":"https:\/\/css-tricks.com\/?p=352959"},"modified":"2021-10-06T07:22:20","modified_gmt":"2021-10-06T14:22:20","slug":"considerations-for-using-markdown-writing-apps-on-static-sites","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/considerations-for-using-markdown-writing-apps-on-static-sites\/","title":{"rendered":"Considerations for Using Markdown Writing Apps on Static Sites"},"content":{"rendered":"\n

If you run or have recently switched to a static site generator<\/a>, you might find yourself writing a lot of Markdown<\/a>. And the more you write it, the more you want the tooling experience to disappear so that the content takes focus.<\/p>\n\n\n\n

I\u2019m going to give you some options (including my favorite), but more importantly, I\u2019ll walk though features that these apps offer that are especially relevant when choosing. Here are some key considerations for Markdown editing apps to help the words flow.<\/p>\n\n\n\n\n\n\n

Consideration #1: Separate writing and reading modes<\/h3>\n\n\n

UX principles tell us that modes are problematic<\/a>. But perhaps there is an exception for text editing software. From vi(m) to Google Docs, separate modes for writing and reading seem to appeal to writers. Similarly, many Markdown editors have separate modes or views for writing, editing and reading.<\/p>\n\n\n\n

I happen to like Markdown editors that provide a side-by-side or paned design where I can see both at once. Writing Markdown is not the same as writing code. What it looks like matters, and having a preview can give you a feel for that. It\u2019s kind of like static site generators that auto-refresh so that you can see your changes as you make them.<\/p>\n\n\n\n

\"\"
Having both edit and preview mode active at once can help you feel more connected to the finished product.<\/figcaption><\/figure>\n\n\n\n

In contrast, I\u2019m not a fan of the one-mode-to-rule-them-all<\/em> design where Markdown formatting automatically converts to styled text, hiding the formatted code (implemented in some form by Dropbox Paper<\/a>, Typora<\/a>, Ulysses<\/a>, and Bear<\/a>). I can\u2019t stand the work of futzing with the app to change a heading level, for example. Do I click it, double-click, triple-click? What if I\u2019m just using the keyboard?<\/em><\/p>\n\n\n\n

It\u2019s not so much that these features aren\u2019t useful, it\u2019s that they break my flow.<\/figcaption><\/figure>\n\n\n\n

I want to see all the Markdown that I\u2019ve written, even if the end user won\u2019t. That\u2019s one thing that I do<\/em> want a Markdown editor to borrow from code editors.<\/p>\n\n\n

Consideration #2: Good themes<\/h3>\n\n\n

Some Markdown editors allow full customization of editor themes, while others ship with nice ones out of the box. Regardless, I think a good editor should have just the right amount<\/em> of styling to differentiate plain text from formatted text, but not so much that it distracts you from being able to read it and focus on the content. Even with the preview pane open, I typically spend most of my time looking at the editing view.<\/p>\n\n\n

Different colors for each style<\/h4>\n\n\n

Since most of the text in the editor isn\u2019t going to be rendered as it would in the browser, it\u2019s nice to quickly see which text you\u2019ve formatted using Markdown. This helps you determine, for example, whether a URL is actually written out in the text or is used inside a hyperlink. So, I like to have a different color for each Markdown style (headings, links, bold, italic, quotes, images, code, bullets, etc.)<\/p>\n\n\n\n

\"\"
Colors tell you which text has Markdown formatting applied.<\/figcaption><\/figure>\n\n\n

Apply bold and italics styles too<\/h4>\n\n\n

I prefer to use asterisks for Markdown formatting everywhere I\u2019m able to (e.g., bold, italics, and unordered lists), so I find it helpful to have extra styling beyond color to distinguish bold, italic, and bold+italic. When skimming it can be hard to differentiate between **this is important**<\/code> and *this is important*<\/code>, whereas **this is important<\/strong>**<\/code> and *this is important<\/em>*<\/code> are easier to separate. It also helps me see if I\u2019ve accidentally mismatched asterisks (e.g., **is this important?*<\/code>).<\/p>\n\n\n

Different font sizes for each heading level<\/h4>\n\n\n

This might be a bit controversial and may split the audience. Code editors don\u2019t show different font sizes within a file. Colors and styles, sure, but not sizes. But, for me, it helps.<\/p>\n\n\n\n

When writing, hierarchy<\/a> is the key to organization. With different font sizes for each heading, you can see the outline of whatever you\u2019re writing just by skimming through it.<\/p>\n\n\n\n

\"\"
Seeing the headings in different font sizes is a subtle way to help you visualize the structure. This is especially helpful for long content.<\/figcaption><\/figure>\n\n\n

Shortcuts and smart keyboard behaviors<\/h4>\n\n\n

I expect all the standard shortcuts that work in a text editor to work. CTRL\/CMD + B<\/kbd> for bold, I<\/kbd> for italic, etc., as well as some that are nice-to-have when writing articles, in particular CTRL\/CMD + (number)<\/kbd> for headings. CTRL\/CMD + 1<\/kbd> for H1, etc.<\/p>\n\n\n\n

\"\"
Making something into a heading should be a simple shortcut.<\/figcaption><\/figure>\n\n\n\n

But there are also some keyboard behaviors I like that are borrowed from code editors. For example, if I select some text and press [<\/code> or (<\/code> it won\u2019t overwrite that text, but, instead, enclose it with the opening and closing character. Same for using text formatting characters like *<\/code>, `<\/code>, and _<\/code>.<\/p>\n\n\n\n

\"\"
A good Markdown editor won\u2019t overwrite your text when you select it and press a valid Markdown formatting character.<\/figcaption><\/figure>\n\n\n\n

I also rely on keyboard shortcuts to create links and images. Even after more than five years of writing Markdown on a regular basis, I still sometimes forget whether the brackets or parentheses comes first. So, I really like having a handy shortcut to insert them correctly.<\/p>\n\n\n\n

Even better, in some editors, if you have a URL in your clipboard and you select text then use a keyboard shortcut to make it into a link, it will insert the URL in the hyperlink field. This has really sped up my workflow.<\/p>\n\n\n\n

\"\"
When I have a URL in the clipboard and use the create link shortcut, it assumes that\u2019s what I want to link to. Handy!<\/figcaption><\/figure>\n\n\n

Bonus feature: Copy to HTML<\/h4>\n\n\n

The editor that I use most often has a one-click \u201cCopy HTML” feature (with keyboard shortcut) that takes all of the Markdown I’ve written and copies the HTML to the clipboard. This can be very convenient when using an online editor (e.g., WordPress) that has a code\/source option.<\/p>\n\n\n\n

\"\"
Easy peasy!<\/figcaption><\/figure>\n\n\n

Consideration #3: Stand-alone editor vs. CMS\/IDE plugin<\/h3>\n\n\n

I know that a lot of people who work with static site generators love their IDEs and may even jump back and forth between code and Markdown in a single day. I often do. So I can see why using a familiar IDE would be more attractive than having a separate app for Markdown.<\/p>\n\n\n\n

But when I\u2019m sitting down to write a page in Markdown or an article, where I\u2019m focusing on the text itself, I prefer a separate app.<\/p>\n\n\n\n

I\u2019m not fanatical about using standalone Markdown editors over IDE editor or plugins; I use one occasionally for complex find-and-replace tasks and other edits. As long as it offers the benefits listed above, I wouldn\u2019t try to talk anyone out of it.<\/p>\n\n\n\n

Here are a few reasons why a standalone app might work better for writing:<\/p>\n\n\n\n