/ How to

How To Embed Code Blocks in Online Articles on Medium Publishing Platform

As a software engineer and technical writer with over 5 years of experience creating technical tutorials and documentation, I often need to embed code blocks to demonstrate concepts or provide examples.

When writing on the Medium platform, embedding formatted code requires using Markdown. Markdown is a simple formatting syntax that converts plain text into HTML with just a few keystrokes. The major benefit of Markdown is readability – you can easily scan Markdown text and understand the formatting.

In this comprehensive, 1500-word guide, I’ll cover everything you need to know to embed code blocks within your Medium articles, including:

Why Embed Code Blocks?

Here are some of the top reasons for embedding code blocks:

  • Demonstrate code examples: One of the most common reasons is to provide concise code examples to demonstrate a concept, framework usage, or API calls. These help readers better understand the topic.
  • Highlight syntax: Code blocks allow you to highlight syntax for many programming languages. This makes the code easier to read and understand.
  • Display output: You can show example input and output by embedding separate code blocks. This helps explain the behavior.
  • Improve readability: Code blocks stand out from normal text, allowing readers to easily spot code examples. This improves the overall readability.
  • Share reusable snippets: Code blocks allow you to share reusable code snippets that readers can test out themselves.

Markdown Code Block Syntax

The Markdown syntax for code blocks is easy to learn and use. Here is the basic format:

```
// Code goes here
```

To create a code block:

  1. Start with a set of 3 backticks ` on a new line
  2. On the next line, insert your code
  3. End with another set of 3 backticks on a new line

That’s the basic syntax. You simply wrap your code in sets of 3 backticks.

Here is an example:

function helloWorld() {
  console.log("Hello world!"); 
}

This renders nicely formatted code with syntax highlighting:

rendered code block

Multi-line Code Blocks

You can have multi-line code blocks by adding new lines within the backticks:

```
function helloWorld() {
  console.log("Hello world!");

  console.log("Welcome to my article!");
}
```

This would render a code block with two log statements on separate lines.

Specifying Languages

You can specify a coding language to activate syntax highlighting for that language:

```js
// Javascript code
function hello() {
  return "Hello!";
}
```

Or other languages:

```python
# Python code 
def hello():
    return "Hello!"
```

Medium supports syntax highlighting for dozens of languages. Refer to their documentation for the full list.

Best Practices for Code Blocks

Follow these best practices when adding code blocks:

  • Explain the code: Always provide some explanation of what the code does and how it relates to the topic. Don’t just embed code without context.
  • Keep code concise: Try to keep code examples short and concise, showing only the relevant parts. Don’t embed huge code listings.
  • Check validity: Double check that all embedded code actually works as intended. Readers may try out the examples.
  • Use horizontal scrolling: For wide code blocks with long lines of text, activate horizontal scrolling to improve readability.
  • Provide live embeds: If relevant, use sites like CodePen or JSFiddle to embed live, executable code examples.

Common Issues with Code Blocks

Here are some common issues to avoid:

  • Accidentally breaking a code block by removing the backticks too soon. Always check that the code renders correctly.
  • Incorrect syntax highlighting when the wrong language is specified or not specified at all. Set the correct language.
  • Code errors or warnings displayed in the rendered output if the code doesn’t actually run properly. Validate all code.
  • Long code lines that stretch far off the page, hurting readability. Use horizontal scrolling.
  • Lack of explanation for what the embedded code is doing. Always explain code relevance.

Embedding Code Pens and Live Code

In addition to static code blocks, you can embed live, executable code examples using sites like CodePen or JSFiddle.

For example, this CodePen embed shows a simple JavaScript clock app in action:

See the Pen Analog Clock by Michael (@retrog4m3r) on CodePen.

Check the documentation for CodePen and JSFiddle to learn how to embed examples. This allows readers to interact with live code instead of just viewing static code blocks.

Summary

Embedding code blocks is essential for technical articles and tutorials. By following Markdown syntax and these best practices, you can effectively demonstrate code examples on Medium.

The key is to always explain your code, keep examples short and concise, validate correctness, use proper syntax highlighting, and consider live embeds when possible. Avoid common formatting issues that break rendering.

Related Posts