Sharing code examples with Carbon
dAVE Inden

dAVE Inden @daveskull81

About: Maker of electronic noise | Drinker of coffee

Location:
Seattle
Joined:
Dec 2, 2017

Sharing code examples with Carbon

Publish Date: Feb 20 '19
90 27

I often find myself thinking about the best way to share something like a code example. Gists seem to work well, especially for something more complex than a function that makes up more than a few lines. But, when you do have something that is only a few lines of code that can seem like overkill.
My next thought goes to taking screenshots of my text editor. This has drawbacks as well since it can take multiple attempts to get something right that will embed well wherever I am putting the example.

Today I came across this tweet from @emmawedekind.

I was reminded that I have seen code examples that look like this before on Twitter. I really like how it looks. The code is clear, has highlighting, and the whole result just looks really polished and professional. This is the kind of resource that communicates clearly and helps to elevate the content by looking nice.
I asked Emma how they created the screenshot and they pointed out the website Carbon to me. It is a really neat site built by Dawn Labs that is free to use. You can choose from various themes to adjust the colors. There is a setting for the language you are using so that it gets the highlighting right. You can export the image out to PNG or SVG for use online or just tweet the picture directly from there if you want.
The results look really nice.
Example Javascript code
I really like how it takes the guess work out of creating code example images and leaves you able to focus on the code that you are trying to share. I definitely suggest checking it out and seeing if it can help you.

Have you used Carbon before? I'd love to see examples of how folks have used this in their own work. Let me know in the comments!

UPDATE (Mar 2nd, 2019)
Multiple folks in the comments have pointed out the accessibility issues with using only images to share code as it hinders someone using a screen reader to be able to consume the content fully. Screen readers won't read out the content of the image and instead use the Alt Text set for the image.
It's also been noted that when the code is in an image it can't be selected for copying and pasting for review in a text editor.
These are both very valid points. I still think Carbon is an awesome app and is very useful, but this goes to show that it isn't a complete solution and should be combined with other methods of sharing code to ensure everyone can get what they need.
I'd still say to use it for sharing code snippets on Twitter as there really isn't a better way to do it at this time within a tweet. You'd have to link out to a gist or another place otherwise.
As for using code images in content like articles I'd consider using the images as only headers or presentational pieces and then embedding a gist or something else that allows for a screen reader to function and for the code to be more easily shared as some have suggested. Or using the image to show the code and linking to a more consumable version within your text explaining the code.
If you are going to use the image for the main way to communicate the code make sure to set good Alt Text for it to help anyone using a screen reader.
A lot of this can be hard to get right sometimes. I found some good resources on Twitter from Marcy Sutton who replied back on this tweet.

Comments 27 total

  • Mikael Klages
    Mikael KlagesFeb 20, 2019

    Though I guess it's based on context, I don't really like images of code, since the text in them can't be selected (not sure if they might also make it harder for blind people using screen readers?).

    On the other hand, some websites like twitter don't have support for displaying code, so i can see why it's needed.

    Maybe the best would be a combination between gist and carbon, that lets you post both an image and a link to the gist? Or maybe a site that embeds the code as an image in the preview of the link.

    • Oscar
      OscarFeb 20, 2019

      The screen reader concern is valid. The example in the original post will be announced as «Example Javascript code». You need to be careful with your alt tags. On platforms such as Medium were you cannot set alt tags the situation for screen reader users is even bleaker.

      Overall I think Carbon and similar tools are pretty good for illustrative purposes (think Open Graph or intro images) but are not an option for the core content of a text.

    • Miklos Bertalan
      Miklos BertalanFeb 20, 2019

      This is true. Based on experience Carbon pictures yield a lot higher engagement rate than markdown code snippets or gists though.

      I usually use Carbon for cover images and tweets (where I need that click) and stick with real snippets in articles.

      • dAVE Inden
        dAVE IndenFeb 22, 2019

        Great points. I will admit that I didn't think about screen readers when I wrote this article which is a whole other issue. It's definitely important to think about the potential audience and how they may need to consume the content. I am also very bad at writing alt text. I never know how much to say. Is it a good idea to have detailed alt text? Is that what folks with screen readers expect? I want to make any content I create here as accessible as possible to folks. Is there any good examples of sites that use alt text well?
        I like the idea of using the examples images as cover images / section headings on articles and in tweets. Then in core content of stuff one can embed gists and link out to them as needed.

        • Mikael Klages
          Mikael KlagesFeb 22, 2019

          I'm not sure to be honest, I remember reading a tweet about how the text should describe only what can be seen in the image, and not additional information that the viewer might not know.

          A quick google search led me to this site, in which case I guess code would be "complex information". Maybe a longdesc code pointing at the raw code would work?

          Though I don't have any experience with screen readers or helping with accessibility for them, so I don't know how much the different solutions might help, or which ones exist.

          • dAVE Inden
            dAVE IndenFeb 23, 2019

            That's a good site. I saw a Tweet last night from Jessica Rose asking about wanting information on writing good alt text. Marcy Sutton replied with some great information in this Tweet with links to a webinar about someone using a screen reader and their experience on the internet along with a decision tree for how to decide on what to put in alt text. It looks like some great info.

    • Bhupesh Varshney 👾
      Bhupesh Varshney 👾Feb 21, 2019

      Yeah that's a cool idea
      I tried contacting Dawn Labs 😅 and suggested to make an api(i would love to make one) so that 3rd party apps could integrate carbon's Feature
      But currently they are sticking with the current platform 🙂

  • Pierre Bouillon
    Pierre BouillonFeb 20, 2019

    I really like this tool ! I even use it to build my CV.
    Carbon is totaly worth sharing and awesome to include code in your presentations or share examples with your team, as long as they don't need to copy it.

    • dAVE Inden
      dAVE IndenFeb 22, 2019

      That's awesome! I really like your CV. I have played around with the idea of presenting my own career info as JSON as well. That is fun. I agree on it being good for presentations. Others have brought up the lack of being able to copy the code as well, which is very true since it is an image. I guess it is all about how one uses it to make sure it is the right tool for the job.

  • Kelli Blalock
    Kelli BlalockFeb 20, 2019

    I wanted a code related image at the top of a post I recently made and I used carbon for that along with stencil to put text on top of it. It's not meant for anyone to really read and copy that code though.

    Where I first saw Carbon being used was @samantha_ming's Code Notes on Twitter. I like the way she customizes the carbon images. You can see some on her site samanthaming.com/tidbits

    As already mentioned in other comments, accessibility is a concern if the image is the only way to view the code. It would be nice if there was a good way to make the code acccessible for those using screen readers or those who want to copy and paste the code to run it, like maybe a button to expand the code - but I don't know how to make that accessible or if it would work out well in practice. I'm hoping someone comes up with a good way to handle it where the code can be shown on the same page if someone wants a text version of the code.

    • dAVE Inden
      dAVE IndenFeb 22, 2019

      I like how you used Carbon. That's a great use for it to use it in the cover image of an article. Adding your own text to customize it is great too. I really like what Samantha Ming is doing with code examples. Those look really nice.
      Accessibility is a big thing to make sure the code is still usable to everyone. Maybe the simple solution is to use the code image and make it a link out to a gist where the code can be copied and read by a screen reader. Or the gist could be embedded below the image.

  • Emma Bostian ✨
    Emma Bostian ✨Feb 20, 2019

    Hey! That's me! :D

    • dAVE Inden
      dAVE IndenFeb 21, 2019

      Yup. Thanks again for the tip! :)

  • Jaaki
    JaakiFeb 20, 2019

    Nice, been wondering about this too.

  • Anthony Tomson
    Anthony TomsonFeb 20, 2019

    If you use Visual Studio Code, you can use Polacode : marketplace.visualstudio.com/items... 😉

    • Avalander
      AvalanderFeb 20, 2019

      That's really neat, thanks for the pointer!

    • dAVE Inden
      dAVE IndenFeb 22, 2019

      That's super awesome. Thanks for sharing that. I do use VS Code. I love how many cool things can be found for working in VS Code. It seems to have everything.

    • Keff
      KeffDec 19, 2019

      Cool, this is really nice! I will use it!

  • Miklos Bertalan
    Miklos BertalanFeb 20, 2019

    Thanks for this article. I love carbon and I think it deserves more recognition.

    A tip for new users: click on that sneaky settings button in the top right corner. I usually find a few things (like the default shadow) a bit annoying but pretty much everything can be customized.

    • dAVE Inden
      dAVE IndenFeb 22, 2019

      Thanks! I'm glad you liked the article. I obviously agree that Carbon is really neat. :) Great tip on the settings button. There is a lot in there to customize.

  • Andy Pickle
    Andy PickleFeb 21, 2019

    I’ve been wondering this myself!

  • John Alcher
    John AlcherFeb 24, 2019

    A carbon generated image + a link to a gist would be the perfect combination.

  • Adrian
    AdrianFeb 24, 2019

    I'm amused and happy it has syntax highlighting for VHDL

  • Rohan Sawant
    Rohan SawantNov 16, 2019

    Ha! I had no idea I wanted to know this, but apparently I did.

    Nice! ✋🏽

    • dAVE Inden
      dAVE IndenNov 17, 2019

      Awesome! I’m glad you enjoyed it.

  • Ben Sinclair
    Ben SinclairDec 4, 2019

    I made a post about why this is a bad idea a while ago (but after you wrote this one): dev.to/moopet/embedding-code-in-po...

    Other people have talked about accessibility, so I'm going to add something else to the mix: potentially confusing UI.

    There's a constant desire burning in the back of the eyes of everyone who calls themselves a "designer", and it's the desire to make things look like they're made by Apple. In Carbon, it extends to adding fake window controls to the image. There's literally no reason for this apart from someone's sense of aesthetic trumping their consideration for the end-user.

    At best, you'll get something that clashes with the UI on your user's display, since they're using Windows or Apple have changed their colourscheme again.
    At worst, people will spend time clicking them to see if they afford functionality like copying or viewing as raw text.

  • Lonli-Lokli
    Lonli-LokliMay 15, 2021

    As I see they support embedding in Medium, so you can just paste the link in post and will render with image. Have you tried it with Dev.to?

Add comment