Ben Sinclair

Posted on May 31, 2019 • Edited on Jun 29

Embedding code in posts

#a11y #ux

As I read articles on here, and on other sites like Medium, I sometimes see people post pictures of their work.

Services like Carbon let you paste code in and get a pretty version as an image.

It looks pretty sweet. It's nicely coloured. It has decent contrast. It invariably makes it look like you use a Mac.

And it's still totally inaccessible.

You can't reasonably put a great swathe of code into the alt text for an image. On hosted platforms where you have a limited number of options, you generally can't do something clever with figure vs. code to let people choose the one they want.

However, these same platforms also natively provide code embedding options, with language-specific syntax highlighting. In markdown, it's as straightforward as pasting your code inside triple-backticks. You can force a particular language for the syntax-highlighting by including the language type directly after the opening ticks.

```
This will be enclosed in <pre> tags.
```

```js
// This will be highlighted as if it was javascript
```

The resulting code is still heavily marked up to handle the colours and spacing, but it's a lot more accessible:

Stylesheets can handle it at different viewport sizes without ending up with really tiny text.
It will respect the font sizing overrides you have set in your browser.
You can copy and paste it into your own editor with your own font configurations.

This serves more purposes for everyone, not just people with limited vision:

When replying to a post you can copy in relevant sections of the original code without having to open two browsers side-by-side and do it all by hand.
You can paste that code into your own editor and try it out.
You can switch on that trendy new dark mode your browser/Window Manager/OS has and - if you're lucky - the site's styles will respect your settings.
You can search for posts containing certain half-remembered bits of code without the expectation that the host site has a million-dollarpound OCR AI system prepared to spare CPU cycles from its regular job of trying to take over the world.

What about other third-party code hosts, like Codepen et al?

They're good, too. Especially if

You're on a site that lets you embed scripts but doesn't natively support code highlighting (e.g. a hosted blog)
Your code is a fully functional example that can be run as a demonstration, rather than just shown as a snippet.
You're happy to add a dependency on another service, with all that entails (more points of failure, potential fees, etc.)

Sharing Code Snippets on Social Media, the accessible way! [Quicka11y]

GrahamTheDev for tota11y.dev ・ Sep 19 '23

#webdev #socialmedia #a11y #tutorial

Top comments (9)

Vincent A. Cicirello • Sep 19 '23

Hi Ben. I found your post through a link in a comment of a recent post. Very nice writeup. There is a way to actually show backticks in a code block without using a different symbol as a stand-in.

If you want to show the backticks in a code snippet, you can put 3 tildas ~~~ on the line before the opening backticks and then again on a line after the closing backticks. Here is an example.

```Markdown
## Example markdown block
Blah, blah, blah...
```

I don't know if this works in all flavors of Markdown, but it does here on DEV.

Ebenezer Enietan (Niza) • Jan 16 '23

This is really Good

ItsASine (Kayla) • May 31 '19

When replying to a post you can copy in relevant sections of the original code without having to open two browsers side-by-side and do it all by hand.

You can paste that code into your own editor and try it out.

🙌

Ben Sinclair • Nov 8 '19

When I draft things they look fine in preview. Well, not 100%, previewing liquid tags in comments is a little shaky. But posts look ok to me in draft.

Is it possible that in drafts there are different classes on the page and you have a browser extension that's blocking something?

Ben Sinclair • Nov 8 '19

I'll do triple backticks here:

const testString="Let's see what happens here";

Does that look right for you? Can you try the same in a reply?

Grant Riordan • May 18 '23 • Edited

I could counter argue this with three points:

As someone who writes on both DevTo and for FreeCodeCamp. What I tend to do is do both. I place an image of the code with styling and formatting, so people can see the code as they would on an IDE / Code Editor. Followed by the code in a code snippet for accessibility (best of both worlds)
By using a snapshot of the code , it also offers the reader the opportunity to write it out by hand. In my opinion this is not a bad thing when teaching someone something. The task of writing something out by hand, (not just copy and pasting) can help readers to learn the concepts, familiarise themselves with the syntax and actually understand the code. More times than not, an article is being written to promote learning sharing knowledge, on the cases where it's to solve a problem / fix a bug. Then this is where I'd agree with you, just utiliae code snippet markdown.
It's also worth remembering code snap tools aren't just for writing articles. They can also be useful for just sharing code problems with team members via Slack, Jira and other forms. It's much nicer receiving a styled code snippet on Slack, than they're default code snippet markdown.

Ben Sinclair • May 18 '23

I see your points, but counter-counter with these:

Seeing the same thing twice in an article is just plain weird. It'd look like a mistake, especially since the platform will apply its own syntax highlighting, etc., which will look different.
While I guess I get the motivation, you're explicitly deciding to exclude people with accessibility needs in order to force people not to copy the code.