Writing Guide 🔭

Follow these and you're in good shape!

Want to get published on Scotch.io? We are very rigorous with our approval process and only the highest quality articles get approved.

  • Solid English grammar
  • No spelling errors
  • Post has to be written in Markdown (No HTML)
  • Use well commented code blocks
  • Use lots of images/screenshots
  • Provide a GitHub repo and demo if possible
  • Use oEmbed instead of iframes


There are an infinite amount of topics to write about in the world of development and programming. If you think someone out there will benefit from what you want to write, we're 100% open to it. Some formats we love to write are:

Don't just show how. Explain why coding choices were made.
  • Build an App with _______
  • What's New in Version X.X of _______
  • Getting Started with _______
  • 10 of the Best _______

For more ideas, visit the post ideas page. Also visit the FAQ if you have more questions on what to write.

Writing Style

Be yourself! Be objective, but let your personality shine through your writing. A mantra we try to live by at Scotch is:

Docs are boring. Be better than the docs.

Written tutorials and building demos should be fun!

Markdown Info

To simplilfy our writing process, we only accept posts in Markdown. Our writing tools provide an easy way to get familiar with the Markdown syntax.


Images are an integral part of tutorials and writeups. They do a great job at helping readers visualize and breaking up the monotony of large paragraphs. Images within the article content can be uploaded at any size and we'll resize it down to `2500px` since very rarely do readers need images larger than that.

Featured Images: Featured images are the first impression you give to your readers. These need to be simple and informative. Usually featured images will consist of a logo for the primary technology being used in the tutorial and the title of the tutorial. For example:

We've created featured guideline templates (PSD and AI) for you to help you create the best featured image possible.

Code Blocks

Our code blocks in Markdown require the language of the code block. For example:

// this is a javascript code block

will turn into:

	// this is a javascript code block

The available options are every language provided by our syntax highlighter Prism.js. Popular languages are:

  • markup
  • javascript
  • css
  • scss
  • json
  • php
  • Check the Prism.js docs for more.

Nested code will automatically be recognized and highlighted.

Embedding iframes

We fully support OEmbed for most of the major embeddable content out there. If you want to embed something, just paste the link to it on its own line, and that's it!

We will handle grabbing the media and embedding the `iframe` code for you. For example, for a YouTube video, just do the following:

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquid hic modi dolore dicta aliquam debitis. Ut ad corrupti ea eaque voluptatibus qui eligendi, fugit suscipit accusamus, sapiente, voluptatem magnam dolore.


Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quod nostrum beatae exercitationem ducimus dignissimos, est hic aperiam, rem cum quisquam praesentium dicta placeat facilis officiis libero consectetur qui nam odit.

This will turn into an embedded YouTube video. Other major providers we support:

oEmbed in action

Currently we have support for the following links. If you need any more, contact us.

Code Repositories

Code repos are greatly recommended as it helps users see real code that they can clone and play with. It is our policy to fork your GitHub repo and use that.

Add instructions to your README to let users know how to use your repo.