Mahyar Erfanian

If you are passionate about it, writing blog posts about coding can be exciting. However, effectively teaching coding concepts requires showcasing actual code. The first approach that comes to mind for someone who have never had to deal with this is probably to take screenshots of code snippets and embed them in your article using <img> tags. However, the method quickly gets out of hand. Managing numerous screenshots on cloud storage and the challenge of editing posts can be overwhelming even for the simplest coding concepts. Additionally, relying solely on screenshots limits flexibility and makes updates quite a headache. So basically we need to find another way to have code snippets in our markup that are not rendered but displayed as is. How will you get around that? A more efficient solution is to leverage the native HTML elements that allow displaying code snippets or embedding live code snippets that platforms like CodePen, CodeSandbox, StackBlitz, etc. offer and that is what I am going to discuss in this post.

Using native HTML tags

If you want to showcase a piece of code without caring about displaying the output, you could benefit from the <pre> and <code> tags in HTML. The <pre> tag, short for “preformatted”, preserves the formatting of the content exactly as it was given. This means that in case your content has consecutive white spaces or line breaks, the <pre> tag will display them, unlike the usual behavior of HTML which ignores extra white spaces and line breaks when rendering text.

That is precisely what we need for writing code snippets; keeping all the code's white spaces and line breaks or otherwise it will not be fun reading the code! Also, you may have noticed that the <pre> tag displays text in a monospaced font which is exactly how we're used to reading code. Perfect!

There is another important HTML tag to learn about in this context and that is <code>. While we can display preformatted content in the <pre> tag, if our preformatted content is code, the appropriate semantic HTML tag to use is <code>. The way that we combine these tags is placing the <code> tag as a child element of the <pre> tag. Visually, you might not notice any difference by including the <code> tag as the child element of <pre> but this tells the browser that the preformatted content is actually a piece of computer code rather than normal text.

Now let's consider another scenario: what if the code snippet that we want to show is HTML code? Will we still manage to display the code rather than rendering it? Unfortunately, the answer is no. However, there is a simple way to work around the issue and that is writing escaped HTML. The process is quite straightforward and you don't have to write the escaped code yourself. First, we write our unescaped HTML code in our favorite IDE and then, use one of the numerous online services that transform unescaped HTML code to escaped code such as freeformatter.com.

Syntax highlighting with PrismJs

Now that we can display any piece of code using only native HTML tags, it is crucial to consider readability, especially for longer code snippets. Syntax highlighting greatly enhances code readability, making it easier to understand and follow. To achieve this, we could leverage JavaScript libraries that provide syntax highlighting and many more useful features when it comes to showcasing code snippets. One of the most popular of these libraries is PrismJs which we will be using here.

To use PrismJs for syntax highlighting, start by visiting their download page and selecting a theme that suits your preferences. Additionally, choose the language-specific highlighting packages you'll be using (PrismJs automatically includes HTML, CSS, and JavaScript). You can also pick plugins like "Line Numbers" for numbering lines of code snippets. Once we're done selecting all the features that we need, download the CSS and JavaScript files at the bottom of the page and link them in your HTML code. The last step is to apply their custom class names to a parent element of any code snippet you want to highlight. For language-specific highlighting, add classes in the format of language-xxxx where xxxx is a placeholder for the name of the language (e.g. language-css or language-js). To use the plugins, include their specific class names such as line-numbers.

Finally, with these steps completed, you'll have beautifully highlighted piece of code with line numbering. Sweet! It's worth noting that this is just one way to use PrismJs, as mentioned in their documentation. Feel free to explore the documentation for other ways to leverage their library.

Embedding live code snippets

The last thing to discuss here is to see how to showcase code snippets along with their output. While one method involves writing code snippets and including screenshots of the output. if we want to avoid having to deal with managing of image files, we could embed live code snippets using <iframe> tags from online code editors like CodePen and that is exactly how I managed to show the code snippets along with the output in this article. This method allows interactions with the code which is a great way to learn. To implement this solution, simply write your HTML, CSS, or JavaScript in the code editor environment of CodePen. Then after saving your code, access the “embed” button at the bottom of page that provides the embed code for your snippet which you can directly paste in your markup. This enables seamless integration of live code snippets, enhancing reader engagement and understanding.

Conclusion

Effectively teaching coding concepts in blog posts requires thoughtful consideration of how to showcase code snippets. While at first you might think of embedding screenshots of code, this method can become cumbersome to manage pretty quickly and lacks interactivity. By leveraging native HTML tags, syntax highlighting libraries like PrismJs, and embedding live code snippets from online code editors, such as CodePen, we can enhance the readability and engagement of our blog posts.

With that, I've shared my methods for including code snippets within markup. If you have alternative approaches or insights, I'd love to hear them! Feel free to leave a comment and discuss this further. Happy coding!