Straight to the Point
I like to write, and when I do, I prefer writing in markdown. Lately, people have been asking my writing process involves, so I decided to write it down in this short post. This is my process and in no way should you feel obligated to use it. Hopefully, this helps you.
My Writing Process
All of this assumes I have an idea and I know what I am writing. That in itself is a whole different topic and not covered here. If you want to know how I write, this is the right place to be.
My Goals
I have some primary goals with writing:
- Stable Tools: What I write in must be stable (I don't want to have to rewrite it!)
- Saving: I want to save my articles, so I can iterate, refer back, and always have it.
- Proofing: I want to spell check and grammar check my articles.
- Markdown: I prefer writing in markdown
- Offline: It must work offline
My Workflow
My workflow is short and hits my main goals. So let's get right to the workflow.
- 1 - VS Code
I use VS Code to write my articles. It has excellent markdown support and is super stable which satisfies two of my goals. Plus, I work in this for my coding all day, so I don't have to switch to another tool.
Here are the VS Code extensions I use:
- Markdown Lint
- Markdown Preview
- Spell Right
- Peacock - I color code my vs code editor for writing articles
- 2 - Proofing
I currently use Spell Right (see the link above) for spell checking in my markdown. I then copy and paste the content to a local doc in Grammarly for grammar checking. You can use any grammar checking tools including Microsoft Word.
I find this to be a good step because spell check only catches part of the story. Grammar checking helps to avoid confusing sentences.
- 3 - Push to a Private GitHub Repo
Saving my content and making sure I do not lose it (2 of my goals) are reinforced by creating a GitHub repository for my content. I prefer this to be private as it contains a lot of my writing. I also organize my repository in a way that makes sense to me. I can find my articles quickly, modify them, iterate on them, and move along.
VS Code integrates with GitHub well, and I use this every day for source control. I find comfort staying in my familiar tools to write articles, commit, push, and move along.
Here is an example of my meta in dev.to:
--------
title: How I Write Online Articles
published: true
description: How you can write online articles
tags: devrel, vscode, markdown, discuss
cover_image: https://thepracticaldev.s3.amazonaws.com/i/n0ecqvxjrzh9qy6ekfgy.png
canonical_url: https://johnpapa.net/how-i-write-online-articles/
--------
- 4 - Copy and Paste to Target Site
The target for my articles could be Ghost (where I host my blog), Medium, dev.to, or any number of platforms. Unfortunately, because they are all different, some support various features, and few have an API, I currently copy and paste. Copy and paste only takes a few moments, so it's not a big deal.
Once I paste into the target platform, I generally find something that looks a little awkward. I make my adjustments in the target platform, test it out in preview (not publishing it), and repeat till it is good.
Then I copy the changes back to my local VS Code editor, commit, and push.
- 5 - Publish on my Blog and then dev.to
I publish my content to my blog first, since it is my blog and I like having a home for all of my content. Then I copy the canonical URL for my blog post and that to the dev.to target in the headers by setting canonical_url. Then I'll publish the same article on dev.to.
Cover Image or SketchNotes
I like to add something visual to my articles. I find visuals in articles to help connect the concepts in my mind. Also, it's fun! There are a lot of ways to get royalty free images. Pexels is one of these.
Often I want a very specific image and it is much easier to draw one. This is where I use my sketchnotes. The sketchnote at the top of this article is what I use to plan out my article.
I'll share more on how and why I use sketchnotes in a future article.
Ideas for the Future
I'd love to have an open API for all writing platforms, especially dev.to. Imagine writing locally in your favorite tools like VS Code, and then pressing a command which publishes the article on dev.to! I'm currently discussing some ideas for how I could write such an extension to publish to dev.to. An extension would require an API from a target platform and a bunch of cool features which I could code in the extension (gist previews using liquid embeds, for example). But ... hey ... it would be a lot of fun and very useful.
The great team at dev.to are considering an API. I imagine it one feature in a long list of great ideas they are prioritizing.
Showing the Read Time
I like to see an estimate of how long the markdown will take to read. This helps me know if I hit the right length for what I am aiming for (whether longer or shorter). Here is a post I wrote about this new extension and a link where you can install it.
You can get Read Time here from the VS Code Marketplace
What Do You Do?
I shared my writing process. I'd love to hear about yours! Is yours different? What do you like about it? What do you wish you could change?
Top comments (59)
Wow, our workflow is almost identical! I just always make my cover images in Sketch or Figma, but other than that totally the same setup!
Great minds think alike! :)
I haven’t used sketch. I’m mostly a paper and pen person these days - old school
Agree with this. Nice to have some self validation that my routine is taken by others 😄
If i wants to send ready article using api directly to the website using nuxtjs, how to do it quickly?
This is a great article! Thanks for writing it. I typically follow the same process as you do. I use VS Code for writing my articles and sometimes use paper by dropbox too. Then I copy to Grammarly to check spelling errors and then push to GitHub. I then publish to my blog and cross post on dev.to! I absolutely love the idea of having an API it'll be really cool to try out. Thanks for sharing the extensions too I've been looking for an extension like Grammarly on VS Code but discovered that does not exist.
Hey Gift! Random question: what do you use for the backend of your blog.
I am about to create mine and I have no idea what to use since my stack is frontend.
Hi @Amaks I use Gridsome and it uses GraphQL as the data layer.
Thanks! I hope to get some community contributions too on the extension.
I recently published a gatsby source for Dev.to API. The idea is , you write your content on Dev.to and it would be posted on your website.
Creating your Blog using GatsbyJS and Dev.to API
Aivan Monceller ・ Mar 31 '19 ・ 2 min read
Very cool! thanks for sharing
@john_papa I thought that summiting the same post on multiple sites would hurt the SEO. So, the canonical_url avoid this issue?
Yes. Exactly the idea behind it.
As I am working from a Mac, I use MacDown for Markdown. I am very happy with it. I usually use the images from unsplash.com with some layouts from canva.com. And I also at first publish it on a personal blog first, and then on dev.to through the RSS feed. For version control and history of the texts, I use Bitbucket and local disk backups.
As for a plugin to direct publish from an editor to the target platform, I think, it is essential before publishing to be able to see the style of your blog post on that platform.
I was using MacDown but I'm all Typora now..
Thanks for sharing!
I'm similar but I use a static site for my blog so I just write the content in markdown and push it to GitHub when it's ready (generally done on
master, but if it's a longer piece or a piece for review I'll use a branch).I've then connected up dev.to to the RSS feed for my blog so that once a new post is published on my site it appears on dev.to with the canonical URL linking back to my site. I'll then review it on here (since it's parsing the markdown from the rendered HTML) and publish it.
can you you tell me how to this blog -> rss
I use a static site generator, Hugo, with all the markdown stored in a git repo.
I've just written a blog today about how I do it with GitHub Actions:
Implementing GitHub Actions for an Azure Static Website
Aaron Powell ・ Dec 16 ・ 14 min read
I instantly downloaded the VS Code plugins. Loving it. Thanks for the nice article on your workflow.
Question:
The peacock plugin works only when you're using a workspace, right?
Do you have a dedicated "content writing" workspace? Or do you write alongside the codings stuff that happens to be open?
All the best John 🙌🏻
Yes - Peacock needs a workspace. I have a github repo of my articles, so that is the workspace that i use for writing
Awesome. btw: i used Pexels too, now I'm into Pixelmob.co: it is an "umbrella search page" that searches for images in multiple free image repos (i believe it searches through Pexels, too). Very nice.
Thanks for your reply!
I like the workflow you use. Surely i will adapt your way of writing too 😊
😊choose your own adventure- there are many ways to write!
Sure, thanks for the push!
I use Notion and Figma, sometimes Lightroom. Notion is great for markdown and spell check..you can lock the note, etc. I was using VS Code before, but switched when I started using Notion to manage projects, schedules, work outs, meeting notes, etc. so it seemed the logical place to put writing in as it's always on either my PC or phone.
I haven't had to use until just today, but it also tracks page versions so that you can go back in time and restore it if you accidentally delete something and close the page. Saving happens automatically too!
Very cool! thanks for sharing
We share a very similar work flow for writing articles. Nice job documenting this for others!
Very cool! Thanks for reading this!
nice and useful post. my workflow is similar but i am not yet fully disciplined into it.
I love writing in markdown and I also use Visual Studio and saving posts in a git repo but since I don't have an own hosted blog and I published directly to Dev.to (sometimes copying-pasting to medium) I still have too many drafts only on dev.to dashboard.
I didn't think about the CanonicalURL - very good idea!
Haven-t tried sketchnotes yet. :-)
thanx for sharing
thanks for reading!
Oh I learned about some new extensions I need to add to my Markdown setup! Thank you!
Nice! I’m always experimenting with extensions. If you find any new cool ones let us all know.
I like this article. Thanks to you I now have another viewpoint for writing and revision control of my .md text-files.
I had just added git revision control, to my .md files, after reading an informative tweet an hour or two ago
My markdown editor in win64 has a build-in spellchecker, so I can use that when I feel the need.
Thank you for sharing
Hey I'm a fan of SketchNotes too - what markers are those in the picture above? Is that just the Copic markers or something else? Curious on your pen choices too.
Yeah. Copic markers. I’ll be posting about my tools soon too.
This was a fun read John. As my workflow is pretty different to yours I've written it up in a separate post:
How I Write Blog Posts These Days
David Wickes
Thanks for the inspiration!
Some comments may only be visible to logged-in visitors. Sign in to view all comments.