DEV Community: Knut Melvær

On the limits of MDX

Knut Melvær — Thu, 01 Apr 2021 19:09:22 +0000

I feel I must preface this with some hedging because I'm about to challenge something that many people seem to love: MDX.

I have nothing but respect for those who contribute to the MDX ecosystem. Also, I'm totally the type of person that would love MDX. I have been writing in Markdown since 2004, and one of my first GitHub projects was a jQuery-based markdown footnotes plugin for Wordpress (jeez louise don't use this!). At university, I had a whole MultiMarkdown-to-LaTeX setup in Sublime Text with pandoc, BibTeX, and PDF preview with Skim going for me. It was kinda great (at least for the two weeks the setup worked)

I don't think MDX should be “considered harmful”, nor that everyone should stop using it. But I think there are some things worth considering before locking your, or rather, others’ content to it. And I'm writing this knowing there might be things I've missed or not considered. Feel free to respond to me with your own blog post, or on Twitter. I don't think this is the hill I want to die on though. So I'll allocate no more than 3 hours to follow up on this discussion. Use them wisely.

With that out of the way. Let's jump into this. 🏊

What is MDX?

If you go to mdxjs.com it self-defines as “an authorable format that lets you seamlessly write JSX in your Markdown documents.” For those not in the know, JSX is “an XML-like syntax extension to ECMAScript without any defined semantics.“ (at least as proposed by the draft specification). In order words, MDX, that is, the MDX precompiler, lets you combine the templating syntax usually found in React.js projects with Markdown. It looks something like this:

# Hello, *world*!

Below is an example of JSX embedded in Markdown. <br /> **Try and change
the background color!**

<div style={{ padding: '20px', backgroundColor: 'tomato' }}>
  <h3>This is JSX</h3>
</div>

It may look like HTML, because it does, but it's JSX. The intriguing part with MDX, but also the… uhm… problematic part, is that you can do stuff like this:

import { Button } from './Button'

# Hello world

Hello, I'm still an mdx file, but now I have a button component!

<Button>Click</Button>

(example from the docz.site)

Yep, you can import JSX components and embed them with your run-of-the-mill Markdown prose. If you're documenting your JSX based component library, which is what Docz let you do, this makes all the sense in the world. MDX is also used to author slide decks in mdx-deck, which is very appealing if you're tired of clicking around in Keynote/PowerPoint/Google Sheets. Which many of us are. I'm not denying the appeal or usability of MDX for certain things for certain people.

From a React developer’s standpoint that it's used to writing JSX, MDX seems to be touching on the ethos of Markdown, at least as John Gruber, its original creator, introduce it on daringfireball.com:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Markdown has always allowed inline and block-level HTML to express things outside of the syntax. Because HTML was the end product. In that way, MDX isn't much different. Markdown's key feature though is "easy-to-read, easy-to-write". I'm not sure if MDX keeps within, or moves away from this general intent. Gruber made a syntax that was easier to read and write for anyone not familiar with HTML. I'm not convinced that JSX solves the same problem.

What is the problem MDX tries to solve?

Markdown was designed at a time where most of the web authoring was still done in HTML. It was also designed when web content was mostly text and images. This isn't the case anymore. Web content has moved towards a much richer set of components, from embeds to interactive code blocks, to between-paragraphs call to action.

MDX seems like an attempt to make these components available to the author in the same syntax used in frontend development (well, as long as your frontend development uses JSX). And that's pretty much it. I think.

But this problem has been solved already. With something they call “rich text editors.”

There's plenty of content platforms with plenty of rich text editors that spew out plenty of different formats, including markdown, HTML, and abstractions as MobileDoc and Portable Text. Medium gained popularity thanks to its smooth authoring experience, Notion now seems to have taken over that hype. Void of HTML and Markdown (well, markdown-like shortcuts works, but is not a requirement), but with rich embeds. Arguably, these interfaces are more friendly and more accessible than learning Markdown, or MDX.

There had to be at least one reason for Slacks introduction of a rich text editor, yes, it wasn't very well executed, and we got Markdown back (I actually got used to the RTE), but I suspect they actually attempted to solve real user experience problems: Not everyone wants to learn Markdown.

Hey, I'm writing here!

I have written React for 20 years (that's recruiter for “since 2015”). I should know how to use my keyboard to paint beautiful JSX components with some lovely props and all that. But for some reason, when I have been made to write MDX. It. just. doesn't. work. I mess the syntax up all the time. Forget that I can't actually be writing Markdown inside of an MDX component (without wrapping it in some MDXprovider something). No syntax highlighting (this may have changed at the time you read this). No helpful error to actually point out where I forgot to close that component. Yeah, I know, but I was really supposed to be writing. Not doing debugging of frontend code.

And yeah… speaking of those components. Most times I had to use MDX, it was to contribute to someone else's documentation. So that means that I had to actually look up a bunch of documentation just to make a code example or a “note”. Sure, I could just TK'ed those parts (and I did), but again, it feels unnecessary for doing something that could be seamlessly solved with a text editor.

This my totally subjective experience, but for now MDX is introducing a level of friction that I'm not really ok with when I'm writing. Which takes me to the next section. Other people!

So, are we expecting people to use this?

I generally have hesitations dividing people into! “techies” and “non-techies” (I can be persuaded if you actually identify as a Luddite). But I have been through enough projects as a consultant and have been through enough user tests to be very careful in forcing even Markdown on people who go to work to do content. Writing with a markup syntax should be opt-in, not forced upon you.

You expect a person who probably already have too much stuff to do, to:

Learn Markdown
Then learn MDX/JSX and imports
Internalize your component system (that never changes, right?)
Work with plain files
Use git or whatnot to actually get the stuff where it needs to go
Ask you how to troubleshoot their texts _when _it gets borked

Sure, you have managed to persuade your client to do it and that's jolly good. But I know that for most people that don't share our coding interests, this will not fly. Not the bit. Also, you're asking them to put their content into a certain format that arguably marries it to presentation. That's probably OK for a slide deck, but less OK if that content is actually describing something of value inside of your organization.

And it has nothing to do with people being "technical" or not. Most content people I know can spot an apostrophe from a grave accent after two jaegers after a seminar. They know how the syntax works. At least some of the time. It's about what we can reasonably expect people to have to deal with. Should they be learning to write JSX components, when frankly, that's your job?

“But Knut, I have this client and they love it”. Sure, that's great for you and your client! But now you have another challenge. That client may want their content elsewhere. Or well, redesign their site the year we all do everything in WebGL. Or they just want to switch out their design system with new components. Yes, I know you have an AST. But you know what's better than an AST? Not to have to use an AST.

Because it's not only moving between formats and languages, it's also how you actually structure your content by what it means, and not after the whims of a specific presentation.

You can't unmix cake

I work for a company that promotes structured content, so you should see this coming from a mile away:

For most uses of MDX you will end up mixing specific presentation concerns with your content. This is not great.

Yeah, it kinda worked for HTML. Until something called iOS came along. And then you had an icky problem. Sure, you could parse it. But have you ever tried to parse real-world HTML? You probably rather spend your afternoon on something different.

For people working with content strategy, content is best stored as ingredients from which you can bake the things that you need when you need it. They have been preaching “structured content” for ages and fighting with CMSes that force content into WYSIWYG page builders and make editors copy-paste their texts around in small layout boxes prisons.

Yes, technically you can be really semantic with MDX too. Compose your components to be great meaningful abstractions, not get tempted to use that style attribute, and keep everything neatly separated in their own documents. But there's little in the design and practice of MDX that promotes this use. It is promoted as a way to build rich visual presentations.

Sometimes you want to make a cake, and that's fine. But you should think really hard if you could feed a lot more people for a lot less effort if you hadn't made the cake in the first place. Ok, this metaphor is pretty tired now. The point is: You should think really hard about how you want to be able to work with your content, the inclinations of whom you want to work with your content, and finally, how sustainable and flexible your structuring of it is.

The obligatory section where I try to sell you our thing

I get it. I get the tangibility of flat files. I get that it feels good to take your coding skills into your prose. But it's not the best way to work with content. Text editors with familiar affordances that produce typed rich text that can be queried and serialized into whatever you need are better. Where developers can define the data structures they need, and editors get easy-to-use tools to get their work done. Like what we're building at Sanity with Portable Text.

But it doesn't even need to be Sanity. After we launched with Portable Text, others have recognized that storing rich text in JSON structures has its advantages. No, you will never want to actually read or author the JSON, but you shouldn't need to. That what's React and JSX is best for:
Building the editorial experiences that don't come in the way of writing. That can be reused across frameworks, programming languages, and redesigns.

Closing remarks

(take a minute to appreciate that subtle pun)

With that out of the way, let me reiterate that I don't want to belabor the people behind MDX and adjacent technologies. It obviously brings some people joy. You shouldn't feel bad for using it either, but now at least you have some counterpoints to make better decisions from. Maybe someone gets inspired to prove me wrong and make a structured content pattern library for MDX. That would at least be something. Or use some of my aforementioned allocated three hours of discussion time to tell me everything that's wrong with the Portable Text specification (I welcome it actually if it can make it better).

But do make sure you have considered if MDX solves the problem you really should be solving, or if it only tickles your developer fancy.

Smash your writer’s block with The Hulk Summary™

Knut Melvær — Thu, 30 Jan 2020 07:06:23 +0000

WRITING IS HARD
YOU THINK TOO MUCH!
WE HAVE A SOLUTION
THE HULK SUMMARY!
CHANNEL INNER HULK VOICE!
BULLET LIST!
FEW WORDS
SAY IT. EFFECTIVE!
NOW, SMASH CAR!

Look, when you work with content, it’s not always easy to get going. Perhaps you only manage to come up with the same tired clichés, or you’re too close to the product and find yourself knee-deep on a tangent describing how the design choices were inspired by something your uncle said in a birthday party.

Whatever it is that keeps you from writing that succinct post that presents the what, how, and why to your readers without wasting their time, there is a remedy. We called it “The Hulk Summary”.

The method is simple. First channel your inner Hulk voice (everyone has one hidden in them somewhere), add a touch of rage and use it to describe whatever you need to get writing on. Hammer down that shift key (caps lock is a cop-out) and type max 4 words for each bullet to capture the core sentiment of what you’re arguing. The constraints will set your mind free.

You might not find crude shouting methodology enough to tease out the core of what you try to say. I'm happy to announce that The Hulk Summary™ is fully compatible with renowned communication frameworks whose efficiencies are proven by probably too expensive consultancy hours, such as the SCQA-model from The Minto Pyramid Principle. Put differently:

WHAT SITUATION!
COMPLICATION! DIFFICULTIES!
I HAVE QUESTION!
ANSWERS ARE DUE.

This method will most definitively not be developed further. We have loads to things to ship over at sanity.io. But now that it is introduced to a wider audience, we would love to hear your success stories about how it saved your whole content marketing department from writer’s block and pencil fear. Or how you made an interesting friendship from using it as a quirky icebreaker at a gathering. Literally hit us up on Twitter and let us know, hashtag thehulkmethod.

(No Banners were hurt in writing this blog post.)

Ode to LICEcap, the simple GIF screen capture tool

Knut Melvær — Sat, 26 Oct 2019 17:28:17 +0000

The folks at Apple Computers Inc. really wanted me to upgrade to macOS Catalina, so I did. After having nervously lingered in front of the unmoving progress bar of impending doom for two hours while the upgrade script made sure that all of my millions of node_modules files had the correct sandboxed permissions, I was finally let into my tool of digital self-expression again. Only to discover that the brilliant engineers of Palo Alto had decided that 32-bit apps weren’t in vogue anymore. You know, like reliable keyboards and SD-card slots.

Not being able to open my beloved LICEcap, prompted me to think of how much I actually use this app.

But this post isn’t about how Apple has lost its edge with its new perfect circular new campus, but about one of my favorite little apps, the GIF screen capture tool LICEcap.

Not a day goes by without me having to record something I do on the screen. It can be to document some bug I found, show my colleagues at Sanity.io something cool, a clever tweet, or useful visual context when I’m helping other people out some project. I know you should think twice before putting animated GIFs on your webpage (because they tend to be huge), but I sometimes make that sin too.d

There are loads of cool screen capture to GIF tools out there. An obvious mention is Kap by these wonderful people. It does a lot more than LICEcap, and is even written in the world-eating JavaScript programming language. In fact, I used it to screen capture how LICEcap works.

Click to see how it works

Using LICEcap to record some interesting free coding.

But the reason I’m always reaching for LICEcap when I need those moving pixels captured is that it records directly to the file. No post-processing. Apparently, that is a killer feature. Being able to quickly do the screen capture and have the GIF ready for sharing in the instant you stop the recording is really convenient. Turns out, convenience trumps feature lists.

Not a lot of bells and whistles, but enough in most cases.

ICEcap doesn’t have a bunch of options and settings. But that’s fine for most parts. If I need more, that usually means that I should do the recording with something like ScreenFlow instead.

I actually thought my days with LICEcap were over, but writing this post made me discover that a 64-bit version has been out since February 2018, so shame on me.

Doing some minimal amounts of research for this post, I also discovered that LICEcap’s developer is Justin Frankel of Winamp fame.

10x engineers and my approach to Twitter

Knut Melvær — Mon, 15 Jul 2019 22:00:00 +0000

You're probably a bit tired of the whole 10x engineer thing by now, but this post isn't really about that. It is about what I learned from it and how I’m reconsidering my approach to Twitter.

10x what? Context, please.

// Detect dark theme var iframe = document.getElementById('tweet-1149302828420067328-552'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1149302828420067328&theme=dark" }

Investor Shekar Kirani recently posted a thread on Twitter about the traits to an alleged type of engineers/programmers. I think it's safe to say that they are a combination of stereotypes that many people find toxic and problematic in a work environment. The ethos of the tweet seems to be that there are these people that don't fit in with the normal expectations of the workplace (“they don’t like meetings” etc), but will be these efficient, high performing workers that will give you, the founder, an advantage in the race that is product development.

I'll leave it to others to rebuke each and every argument in this thread (just dive into the replies to get an idea), but let me just point out that the best coders I know have tended to be really nice people that have happily shared their knowledge, gone to meetings, had family obligations, and all sorts of desktop backgrounds.

I piled some wood on the bonfire

So Shekar’s tweets struck a nerve and the reactions were plentiful. People were tired by the whole 10x thing before two hours had gone. The sentiment among the outspoken programmers and tech people were pretty unified against the idea that the profile the tweets painted had any basis in reality, and were a collection of traits that had no business being in tech or a workplace. There were also worry that these tweets rehearsed and perpetrated ideas that are shared among founders and investors. Some of the generalizations also made it really easy to mock and satirize the Twitter-thread.

As I've written before, I'm sometimes tempted to do the hot take or go for the satirical smartass comment on Twitter. Shekar’s thread got to me, both because here was this investor promoting something I deeply disagree with, but also because it seemed so out of place to do so in an environment that's just ready to pile on people that seemingly work against making tech a healthier and more inclusive place.

So I tweeted something to the effect that I think it's weird that an investor would say these things publicly, and should have known the response it would get. It simply doesn't seem like a strategic move, even though if one means it. Only I choose to put emphasis on what these tweets said about Shekar as a person, and by “quote tweeting” him. Making the recipients my audience, and engaging him directly.

I got my likes and replies and moved on with the day. I was one of many hundreds, if not more, that more or less mocking wrote Shekar and his thread off. As one does on Twitter, right?

Is this the person I want to be?

And then I got some feedback. A person, whose opinions I care about, told me that I came off arrogant and with little respect to a person I disagreed with, who I didn’t know, on the basis on some tweets. My first reaction was to become a bit annoyed. I just did what you do on Twitter, right? Here's this investor saying outrageous stuff, and I was sticking it to the man. But then I had to reconsider the critique because it came from a place of concern.

I don't know Shekar. I don't know much about the context he's working on in India. But I know that the respect and humanity I found lacking in the ideas behind his tweets were a bit lacking in mine as well. I didn't tweet what I did because I hoped to change anyone's mind or educate them.

I tweeted what I did because I wanted to look smart and part of “good team“. I was virtue signaling. And doing so by throwing timber on a bonfire to a person that probably didn't expect how this thread would blow up. That's not a person I want to be, and I don't think I really was helping promote the ideas and practices we so dearly want in tech.

So I deleted my tweets.

I’m not done thinking about how I approach Twitter

My reconsideration of how I approach Twitter can easily be read as a value judgment of others’ satirical or mocking replies to Shekar’s tweets. This is where I’m ambivalent. Because I do mean and appreciate that there is a place of satire, humor, and jestful creativity to counter destructive ideas put forth by people in power. The site 1x Engineer is a good example of this.

There’s also another side of this, which is that of privilege. I have, as a Norwegian guy in my early 30s, very little reason to feel particularly angry or hurt based on my experiences growing up in one of the safest environments on this planet. But other people have plenty of good reasons to feel and express both.

That’s why I explicitly am framing these thoughts as the reevaluation I’ve done for my own behavior, and put them here in a way to think loudly in public, and to hold my self accountable. So this is how I'll try to approach critique on the web going forward. And frankly, most of these points are not original and have been made by many others before me:

I'll consider that I’m responding to a real person.
I’ll comment on the actions and ideas represented in the tweets.
I’ll consider that the person may have English as a secondary language (as I do), and are not aware of nuances and the implications that certain word choices may have.
I’ll consider what I want to achieve: Is it providing nuance or reconsideration? Is it just blowing off steam? Is it marking a stance?
I will to the best of my ability, try to make it possible for the person to reconsider, or engage me in a discussion.

I believe I know what you’re thinking: What about trolls and people with extreme and hurtful opinions? I don’t really think all people on Twitter is there for “enlightened discourse”, which the points above are aiming for. And obviously, many people know what they’re doing when they say hurtful stuff. As for now, I’ll probably not grant them much of my attention and counter with promoting ideas and activities that make tech a safer and more inclusive (for example, Making tech surviveable: What can men do?).

Is there something I have failed to consider here? Did this make you think about how you use Twitter? I’d love to hear about it!

A year in developer relations

Knut Melvær — Fri, 05 Jul 2019 07:00:00 +0000

Here are my learnings based on my first year running developer relations at Sanity.io. I guess they are rather obvious, but I think they’re worth sharing as they can be helpful for someone starting with developer relations/advocacy.

Cover Image: I was a fan of Syntax.fm’s Scott & Wes before I became a developer advocate. Here I got to meet them at JAMstack_conf San Francisco in 2018.

I’ve been in developer relations for about a year now. Actually, I’ve only known that “develop relations” and “developer advocate” have been specific things for that long. The first time I consciously encountered these titles was when I was offered the role as "Head of developer relations" with my current job at Sanity.io. It seemed to encapsulate with what I could contribute with.

Even though I had never worn such titles before, I had experience in teaching, mentoring, and dissemination, and I had been promoting aspiring developers before. I have a lot of training from teaching theory and methodology at University, I have run web development courses for retirees and beginners, and I have been writing about technology for a long time. I just didn’t know that that was a dedicated job in tech, and not the least, a “scene”. With T-shirts, stickers, books, and Slack groups. With the title, I was also joining a community and a discourse.

1. Find yourself a team that cares

I joined Sanity when they mostly were the developers from the original Bengler team. They made the platform because they wanted a real-time content backend for OMA’s website. In 2017, they converted Bengler into a startup for Sanity. Since I joined, I had to figure out how to do the developer relations part, but also contribute to how we should communicate Sanity in general. I’m very fortunate to be working with some fantastic people, both in terms of talent and experience, who also give an excellent mix of constructive feedback and praise.

That’s perhaps the most crucial part of what motivates me as a developer advocate: It's much more fun when you and your colleagues feel that there’s a stake, that there‘re care and attention given to almost every detail of what we do. I get the sense that we have made this cool thing that we want people to use, because we think it makes their day better, and they will make cool things with it. If you want to work as a developer advocate, be on the lookout of a team that cares. It’s easy enough to forget if the product has a cool flair, or the perks are awesome.

2. Learn to take feedback

That stake, and care, comes with a challenging side too. There will be a lot of opinions, inclinations, ideas, and feedback on whatever you do. The feedback may even be conflicting or just not feasible to follow up. Your job is to mediate the feedback that you get within the company, with that you get outside, and turn it into something constructive and actionable.

I try my best to communicate why we are doing what we do in the weekly all-staff meetings. I also make sure to include nice things people have said about our work to remind the team that they’re doing work that's appreciated by real people. That's the “relations” part of the job.

I give much consideration to the feedback I get from my colleagues, but I don’t always follow it. That's partly having to follow my gut-feelings from all the impressions and observations I've, being "out there", and partly because the advice you're given is for inaction (“We shouldn't do x, y, z”).

I remember that we had a lot of discussion and indecisiveness around creating a new developer community. All the services had drawbacks for sure. My job then was just to pick something, and get it going. So I did. A year after we’re over 1.100 developers in our Slack. Yes, the message retention sucks, yes, it would have been handy to have all our answers indexed by Google. At the same time, the feedback, enthusiasm, and all the questions have been invaluable. We don’t regret it.

3. Talk less, listen more

Speaking of the community Slack. I also remember being super worried about trolls and people that would object to our Code of Conduct. It’s super interesting to see that many of us in tech are occupied with figuring out how we can make sure that people feel welcome, included, and safe. Since I became more aware of people’s shitty experiences, and my own mostly hassle-free experience in tech, I must admit that I many times have been afraid of inadvertently saying something that may cause someone discomfort.

Because I used(?) to be much more of a "here’s my five cents”-guy on Twitter and such (well 600 words in, I guess I still kinda am), but I have consciously abstained from posting and replying to stuff that may have irritated me. I use two thought technologies (which I picked up from the Back to Work podcast). The first is saying out loud: "I will not let this bother me." The second is to question "Is this the hill I want to die on?". They actually work — most of the time.

Instead of being such a smart ass, I have been trying to observe and listen instead. It is something I still work on being better at. I have been listening in two ways. First, I have made sure to follow a more diverse cast of people, and I have been trying to take in the stories of those who display concerns about the inclusiveness of tech. I’ve also tried to contribute with some thoughts and took part in organizing Global Diversity Call For Papers Day. And it has been humbling. And frankly, it’s nice not being the one offering the hot take or glib tweet (well, there’s still some occasional ones).

4. Learn how to take time off

Honestly, I’m still rubbish at this. So I write this as much as advice for myself as for you. Thing is, there’s an infinite amount of tasks you can do as developer advocate: there’s always another talk proposal, demo, blog, or some documentation you could improve. There are always people that need help with something. So you have to draw some lines. Now, it’s hard to offer exactly what those lines should be because it also is highly dependent on where you live, whom you live with, if you have a family, how old you are, etc.

I’m fortunate in having gotten professional help for recurring depressions, and have mostly figured out how to live with it (CBT worked for me). I’ve been through a burn-out experience when I did my Ph.D. studies at University and got into tech after that – where I felt much more at home. I’m also fortunate in having a spouse that rides dressage. I often tag along to the stables to get some honest off-screen time with our two horses and help her out with grooming, and the many tasks and sorts that you have to do there. I also do my best to get some exercise, jogging and such. Doing something completely different seems essential.

Taking time off is partly on you, but having a workplace that understands that highly motivated people often need help with setting boundaries and be reminded that they need to take time off to not burn out at the office, is important as well. We’re regularly reminded of this at Sanity, and we’re trying to build structures (everything from how projects are planned, to setting expectations) that enable and ensure this as well.

I also think it’s vital for us that has the roles of being a developer advocate to communicate this as well, and to our own discretion share those part of the daily life. It's easy enough to feed into people’s impostor syndromes and impression that you have to work all the time to belong in tech.

5. Take it seriously, but don’t be too serious

As a developer advocate you do an important job. You’re both responsible that other people are successful at what they try to do, and on relaying back to your team what you learn. You are inevitably tied to your workplace and — excuse the marketing term — its brand. If you are approachable and helpful, that will contribute a lot to your company’s success. Even if I had put “opinions are my own” in my twitter bio, my behavior will reflect something back on people’s impression of Sanity, and the work being done there. So I owe to my team to be mindful of how I act and communicate. This position is very different from coming from the Humanities, where you are much more your own agent (at least, this was the case where I was studying).

This connection that you have with your workplace, and the fact, let's be honest, that much of what you’re doing can fall in under the term marketing, also means that people will have certain reasonable expectations of your biases. The serious part is not trying to be coy with whom and what you are representing, and be transparent when you’re discussing things where you obviously have an interest if promoting whatever you do.

At the same time, you are also a person with all the flaws and particularities that comes with that. Sometimes, people will say disparaging things about whatever you’re working on. Or they will dismiss you as a just a biased representative of where you work. That is the time where you shouldn’t be tempted to go into arguments or make a big fuzz. Try to distill whatever legit criticism can be found, and move on.

Being a developer advocate is probably the most exciting job I have ever had. The range of different things you can do and the people you encounter is ideal if you’re motivated by learning new things and are excited by learning what other people are creating. It has been an absolute blast being part of launching the developer community for Sanity, and we have a pretty interesting year ahead of us opening a new office in San Francisco, hiring more people, and preparing for the next step.

I look forward to looking back at the coming year with a new blog post like this. Stay tuned (e.g., by subscribing to the RSS feed)!

Getting started with Webmentions in Gatsby

Knut Melvær — Mon, 24 Jun 2019 10:00:00 +0000

I have been curious to learn more about webmentions and the IndieWeb for a while now. Putting together my new blog seemed like an excellent opportunity to learn more about it. So keep in mind that I’m pretty new to this stuff, and just sharing my learning process as I go along. This is at least a short tutorial to how to get started with making your site webmentions friendly, how to connect them with twitter, start retrieving them with Gatsby, and how to trigger rebuilds on Netlify when new mentions come in. I’ll revisit how to send them in a later tutorial.

I got started on my webmentions journey by reading Chris’ Building Gatsby Plugin Webmentions and Chad’s Embracing the IndieWeb. Both works were helpful to get started, but they left some details out that may have made it a bit easier to grok. I’ll walk you through all the steps, but do check out their stuff as well.

What is Webmentions?

You can read more about it on the IndieWeb wiki, but shortly put: Webmentions is an open source project and a service to send and receive messages and pingbacks between sites. Like we all did with Wordpress back in the day.

The difference are that Webmentions are federated, meaning that you can collect and send mentions from multiple sources. In this tutorial, I’ll start by pulling in twitter mentions via a service called brid.gy.

How to get started with Webmentions

To get started with Webmentions you need to sign in on webmention.io. And to sign in you need to authenticate. And to authenticate you need to put some markup on your Gatsby site that tells webmention.io which service it can use. As per instructions you can add the following using either Twitter, GitHub, email, your PGP key, or you own IndieAuth server. I added Twitter and Github:

<p>
  Follow <a class="h-card" rel="me" href="https://www.knutmelvaer.no/">Knut</a> on <a href='https://twitter.com/kmelve' rel='me'>Twitter (@kmelve)</a>, <a href='https://github.com/kmelve' rel='me'>GitHub</a>, or send him an <a class="u-email" href='mailto:knut.melvaer@gmail.com' rel='me'>email</a>
</p>

So this pretty much looks like your regular piece of HTML. If you look a little closer there is some rel="me" attribute as well as some class names (h-card, u-email). These are microformats (TK), which is an important part of getting webmentions to work. When you publish your site with this markup, you tell webmention that those social accounts are tied to whomever is control of the domain the site is on, and lets you log in via their oAuth-integrations.

As you can see in the figure above, I have a list of webmentions there that you probably don’t have (yet). We’ll return to how to get that list populated with stuff from twitter, but first, we have to add some microformats to our site, to make it webmention friendly.

Adding microformats2 to your posts

Webmentions use a specification called microformats2 to make sense of contents on a webpage. We’ve already started implementing it in the code snippet above. There’s a lot to microformats that I haven’t unpacked for myself yet, but it’s easy enough to get started. You mainly do so by adding some specified class names to HTML elements that have the specific content that webmention use to populate its fields. For example:

<article class="h-card">
  <header>
    <img class="u-photo" src="http://...">
    <h1 class="p-name">The Title</h1>
  </header>
  <p class="p-summary e-content">The summary</p>
  <footer>
    <a class="u-url p-name" href="http://...">The author</a>
  </footer>
</article>

You can use IndieWebify.me or pin13.net to validate your markup. I took a couple of tries for me to get it right. When a webmention service read your page, it will parse the HTML and extract this information into a JSON structure, that may look something like this:

{
  "items": [
    {
      "type": [
        "h-card"
      ],
      "properties": {
        "name": [
          "The Title",
          "The author"
        ],
        "summary": [
          "The summary"
        ],
        "photo": [
          "http://..."
        ],
        "url": [
          "http://..."
        ],
        "content": [
            {
              "html": "The summary",
              "value": "The summary"
            }
        ]
      }
    }
  ],
  "rels": {},
  "rel-urls": {}
}

I ended up implementing these “microformated” elements in my post template and hiding them with display: none. Mainly because I didn’t want an ISO8601 formatted datetime stamp visible on the site. I could probably have used a library like date-fns to format the timestamp, but this did the trick without any dependencies. This is for example how it looks in my Gatsby blog’s React code:

<time 
  className={styles.hidden + " dt-published"} 
  itemprop="datepublished" 
  datetime={publishedAt}
>
  {
    new Date(publishedAt)
      .toISOString()
      .replace('Z', '') + "+01:00"

  }
</time>

Now, let’s head over to the interesting part, namely, getting webmentions into Gatsby.

Installing `gatsby-plugin-webmention`

The easiest way to get webmentions into a Gatsby site is to install the gatsby-plugin-webmention plugin:

npm install gatsby-plugin-webmention
# or
yarn add gatsby-plugin-webmention

Now you can add the following config to the plugins array in gatsby-config.js (obviously replacing my information with your own):

{
  resolve: `gatsby-plugin-webmention`,
  options: {
    username: 'www.knutmelvaer.no', // webmention.io username
    identity: {
      github: 'kmelve',
      twitter: 'kmelve' // no @
    },
    mentions: true,
    pingbacks: true,
    domain: 'www.knutmelvaer.no',
    token: process.env.WEBMENTIONS_TOKEN
  }
}

The webmentions token is the one that you find under "API key" when you’re logged into https://webmention.io/settings. Remember to also add it to the environment where you build your Gatsby site to production (for example on Netlify). If all went well, you’ll be able to query your webmentions in the Gatsby GraphQL API.

In order to get page specific webmentions I did two things:

Generate and put the post’s URL into context from gatsby-node.js
Filter the allWebMentionEntry with the URL aka "the permalink"

There’s probably a handful of ways to do this, but I ended up with just generating the full URL in gatsby-node.js, and passing it in via context, so that I could use it as a query param:

postEdges
  .filter(edge => !isFuture(edge.node.publishedAt))
  .forEach((edge, index) => {
    const { id, slug = {}, publishedAt } = edge.node
    const dateSegment = format(publishedAt, 'YYYY/MM')
    const path = `/blog/${dateSegment}/${slug.current}/`

    createPage({
      path,
      component: require.resolve('./src/templates/blog-post.js'),
      context: { 
        id, 
        permalink: `https://www.knutmelvaer.no${path}`
      }
    })

    createPageDependency({ path, nodeId: id })
  })

And the GraphQL query:

allWebMentionEntry(filter: {wmTarget: {eq: $permalink}}) {
  edges {
    node {
      wmTarget
      wmSource
      wmProperty
      wmId
      type
      url
      likeOf
      author {
        url
        type
        photo
        name
      }
      content {
        text
      }
    }
  }
}

The properties of this query will be pretty self-explanatory when you start to get webmentions data. You can use it to list people who have liked, replied, or reposted your post.

The simplest way to get some webmentions going is to use a service called brid.gy to bring in mentions of your website on Twitter.

Connecting brid.gy

Head over to brid.gy and connect your accounts, I think Twitter makes the most sense, at least at first. Enable the listening for responses. There need to be some tweets that mention your site (by domain name) to there being responses. You can, of course, just tweet your self to get something going.

If you (re)start your Gatsby site in dev mode, you’ll be able to see the same response data in your GraphQL layer. This will make it a bit easier to implement in your frontend template.

Implementing webmentions in your Gatsby frontend

I’m not going to cover much detail here, this is the creative part! It’s pretty much straight forward though. For example, to filter out all the "likes" and show some avatars with links to the "liker", you can do something along these lines (not saying that this is the definitive way to do it):

import React from 'react'

export default function WebMentions ({ edges }) {
  const likes = edges.filter(({ node }) => node.wmProperty === 'like-of')
  const likeAuthors = likes.map(
    ({ node }) => node.author && { wmId: node.wmId, ...node.author }
  )
  return (
    <div>
      <h4>
        <span>{`${likes.length} likes`}</span>
      </h4>
      <div>
        {likeAuthors.map(author => (
          <a href={author.url}>
            <img alt={author.name} src={author.photo} key={author.wmId} />
          </a>
        ))}
      </div>
  )
}

You can use this component where you query for webmentions, by sending the allWebMentionEntry object into it <WebMentions {...allWebmentionEntry} />.

Triggering a new build on a new mention

If you’re like me, you’re impatient and want new mentions to appear when they happen. If you are patient, you can be satisfied by having the new mentions appear whenever you rebuild your site. But if you host your Gatsby site with let's say Netlify, you can use a build trigger to automatically rebuild the site, querying the newest mentions. First, you’ll have to add a new build trigger on Netlify. Copy this, and head over to the webhooks settings on Webmentions. Paste the Netlify URL into the box (no secret is needed), and hit save. And that’s it! (I realize that we can do some interesting things with this webhook, but we’ll revisit that in a later post.)

I would also recommend setting up some build notifications on Netlify so that you can keep an eye. Especially if you’re actually putting some content from the webmentions on to your site. This would be the time I told you that you can delete webmentions, and add someone to your blocklist if this is needed. Hopefully, it will not though.

Congratulations, you’re now a bit more indie!

There’re still some pieces left to the puzzle. We haven’t set our site to send webmentions or pingbacks yet. And there are more sources than Twitter that we can draw from. I’ll surely return with more fun IndieWeb + Webmentions stuff though. Meanwhile, feel free to reply to me on twitter, or even try webmentioning this post if you have constructive feedback. I’ll happily amend this post and follow up with useful insights.

How to quickly set up a Gatsby.js JAMstack website with a headless CMS

Knut Melvær — Wed, 23 Jan 2019 23:00:00 +0000

In January 2019, we released a new source plugin that makes it easy to use Sanity as a headless CMS for a JAMstack website built with Gatsby.js. It's pretty easy to install and integrate with exciting projects on Gatsby. If you're new to the static site generator, or want to test the plugin out, we made a full company website and a headless CMS example, with people, projects, a blog, and some info pages. In this tutorial we'll show how to set it up, and how to run Gatsby in development mode on a web server, to get a real-time online preview of content changes.

The example is a monorepo, containing both the configuration for Sanity Studio, where you'll be editing content, and the Gatsby built website. It's also configured to be deployed straight onto Netlify or Now. You can create a new free Sanity project within it, and be up and running in minutes. Web development in the age of JAMstack is truly fantastic!

We feel safe that you can take our company website example, and make it your own.

Clone or fork the repository on Github

Go to the example repository on GitHub and clone, or fork it from there. You can also run this in your terminal in the folder you keep your web-projects (replace the URL with your own if you forked the project):

    git clone https://github.com/sanity-io/example-company-website-gatsby-sanity-combo.git
    cd example-company-website-gatsby-sanity-combo

Install the Sanity CLI

It's convenient to have the Sanity CLI when working with projects like this, and it doesn't take long to install. Run the following npm command in the command line:

    npm install --global @sanity/cli

Install dependencies

This example use node package manager (npm) for dependencies, you can also use yarn if you prefer that:

    ~/example-company-website-gatsby-sanity-combo
    npm install

Set up Sanity.io as a headless CMS

    ~/example-company-website-gatsby-sanity-combo
    npm run init

Run this command after the install script is finished. Follow the CLI's instructions to create a Sanity.io project for the website. We recommend setting the dataset to public (you can change it to private afterward if you prefer). A dataset is where all you store all your content, kind of like a database. You can have more than one dataset. For example, if you want a content test bed for development.

The npm run init command also deploys a GraphQL API for your Sanity project (Sanity supports both GROQ and GraphQL). The Gatsby source plugin for Sanity uses the GraphQL schema definition to prevent types and fields missing from Gatsby's templating API. As far as we know, this is the only plugin that helps you with that – it's pretty practical!

Start the local development server

In your project folder you have two folders: studio and web.

The studio folder is where you'll find the configuration files for the Sanity Studio, which is an open source editor for your content, built with JavaScript and React. It connects to the hosted API and is real-time, like you have in Google Docs. You can host the Studio anywhere you can host an HTML-file. In the studio/schema folder you'll find the configuration files for all the types and fields. You can tweak and change these later if you want to, but we'll let them be for now.

The web folder holds a Gatsby website, with everything you need set up to render the content managed with Sanity. If you're new to Gatsby, we recommend their comprehensive documentation to learn the basic ideas.

You can start both development servers for the Studio and the Gatsby frontend with a single command:


    ~/example-company-website-gatsby-sanity-combo
    npm start

The studio runs on localhost:3333, and the website on localhost:8000. If you open the website you'll be met with an error message. That's because it needs some content to build. So start by opening the studio and log in.

Go to Site Settings and Company Settings and fill in at least the names. Make a blog post (just some mock content is fine), a project, and some of the other stuff as well. You should give both your blog- and project entries a title, a slug and preferably a Published at date (in the past). Remember to publish the changes (the blue button down left). Although all changes instantly sync with the hosted backend, they won't appear in the public API without being published.

Now you probably need to restart the development server, to get Gatsby to build with the new changes. ctrl + C will quit the current process, and npm start to start it again.

Try out watch mode for Gatsby

If you look at the file called gatsby-config.js, you'll see the following entry in the plugins section:

    {
      resolve: 'gatsby-source-sanity',
      options: {
        projectId,
        dataset,
        // To enable preview of drafts, copy .env-example into .env,
        // and add a token with read permissions    
        token: process.env.SANITY_TOKEN,
        watchMode: true,
        overlayDrafts: true
      }
    }

We have enabled watchMode, which means that Gatsby injects content changes on the fly, without you having to reload the development server, or refresh the browser. Few other source plugins do this. What's even cooler, is that other people can sit in the same studio, and edit content, and that too is instantly reflected on the frontend development server. The plugin only gets access to published changes by default, but try editing something (maybe add an image to the first blog post), push Publish and see if it updates in the frontend.

Add token to see _all _changes

In the plugin, you maybe noticed token: process.env.SANITY_TOKEN and overlayDrafts: true. With a token with read privileges, you give Gatsby access to unpublished documents, such as drafts. When overlayDrafts is set to true, Gatsby will use the draft version of a document if it has access to it. You'll need to save a read token in a file called .env in the web folder to enable this:

    ~/example-company-website-gatsby-sanity-combo/web
    cp .env-example .env

Now you can go to <YourProjectId>/settings/api (Manage -> Settings -> API), and Add New Token. Give it a nice descriptive label, and only read rights. Copy it, and paste it in the .env file:

    ~/example-company-website-gatsby-sanity-combo/web/.env
    SANITY_TOKEN="YourToken"

To load the token into Gatsby, you'll need to restart the local development server again. It will be worth it though.

Get your Gatsby site on the web with Netlify

Maybe you want to tweak the frontend a bit, change the CSS, or make some adjustments. At some point you want to share it with the world though. We recommend that you put your project on GitHub. If you forked it, commit and push your changes. If you cloned it from us, follow these instructions on how to get a local git repo on GitHub.

When it's on GitHub, head over to Netlify and sign up or log in. If you choose New site from Git and find the repository you just updated, everything is set up and ready, thanks to the netlify.toml file in the project. Likewise, if you prefer Zeit's now (or want to use both for ultimate redundancy), you can run npm run now-deploy in the root folder of the project.

To quickly deploy the Sanity studio, run sanity deploy in the studio folder and choose a hostname. Now you can invite two additional users for free on the forever-free developer plan. If you need more, it's $10 per user on the pay-as-you-go on the same plan. Gatsby only uses 2 API request to build the whole site. One for all your content, and one for the schema. So you will get great mileage with our free plan with a Gatsby website. We dig it!

Trigger new Netlify builds on content changes

Netlify triggers new builds when you push commits to a branch that it monitors. The content, however, is not committed to Git. Fortunately, there are other ways of triggering builds, one of them is using webhooks.

If you host your site on Netlify, you can go into Settings -> Build & Deploy and scroll down to Build Hooks. Choose Add build hook, give it a name, and point to the branch you want to build from. Copy the URL, and return to the terminal:

    ~/example-company-website-gatsby-sanity-combo
    cd studio
    sanity hook create
    ? Hook name: netlify
    ? Select dataset hook should apply to: 
    ? Hook URL: https://api.netlify.com/build_hooks/

Now Netlify triggers a new deploy of your site everytime you publish some new content edits.

BONUS: Content preview online on Heroku

This helpful tutorial by Andreas Keller popped up in our feed. He has figured a way to run Gatsby on a development server on Heroku, hence making it possible to get that watch mode with live previews experience on the web. Which is nice if you have editors that can't be expected to run a local development server in the terminal. Let's set it up with the Sanity source plugin to get an unparalleled preview experience!

Install the Heroku CLI

Follow these instructions to install the Heroku CLI. Run heroku login and log in or sign up.

Add gatsby-cli as a dev-dependency

To get Heroku to play nice with the monorepo (it likes its apps in the root folder), we must install the gatsby-cli as a dev dependency in the root folder:

    ~/example-company-website-gatsby-sanity-combo
    npm install gatsby-cli --only=dev

There are also other ways of doing it where you push the web folder, but then you have to put in the projectId and dataset manually in gatsby-config.js, as these variables are imported from sanity.json in the studio folder.

Once you're set, you should do the following:

    ~/example-company-website-gatsby-sanity-combo
    # create a new heroku app
    heroku create

    # set node to run in development mode
    heroku config:set NODE_ENV=development
    heroku config:set NPM_CONFIG_PRODUCTION=false

    # set the project id and dataset, found in sanity.json
    heroku config:set PROJECT_ID=YourProjectId
    heroku config:set DATASET=YourDatasetName

    # add the read token to Heroku's environment
    # make sure that the token isn't wrapped in quotation marks
    heroku config:set SANITY_TOKEN=$(cat web/.env|grep SANITY_TOKEN)

    # add the app configuration to run gatsby on heroku's dyno
    echo "web: cd web && gatsby develop -p $PORT -H 0.0.0.0" > Procfile

    # add the changes to git
    git add Procfile package.json package-lock.json
    git commit -m"Add Procfile and deps for Heroku"

    # push it to heroku
    git push heroku master

    # open the app in the browser
    heroku open

    # check the logs to troubleshoot if things don't work
    heroku logs --tail

This app runs on a free dyno that sleeps after a time of inactivity, and it can take some minutes to start up again. You can of course run it on a paid dyno which gives you full uptime. We cannot guarantee that it will be very stable, since the development server isn't built to actually host a website on the web. If it crashes, you can restart it with heroku restart.

It's pretty cool nonetheless, and undoubtedly useful when you want to give your web editors a way to preview their changes instantly, without having to wait for rebuilds.

How to shift array position in vanilla JavaScript

Knut Melvær — Wed, 19 Dec 2018 08:44:47 +0000

I was helping a user over at sanity.io yesterday doing some content migration, where they wanted to take the last element of an array and put it in the first position. Every time I get a question like this, I like to see if I manage to solve it without going to any libraries. Both because I don't want to introduce more dependencies for the person with the question, but most of all, it's an opportunity for some mental exercise.

So, how to change an array like this:

["Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn", "Walder"]

to this?

["Walder", "Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn"]

My first instinct was to make a new array just targeting the last element with the list length subtracted by 1, and then spreading the rest of the array using splice. Push the green run button to run the code:


    
const theList = ["Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn", "Walder"]

const newList = [theList[theList.length - 1], ...theList.splice(0, theList.length - 1)]

console.log(newList)

Some of you will already have guessed why this is a bad idea, and some of you will be like me and always mix up splice and slice. Let’s see what happens with theList when we run the code above:


    
const theList = ["Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn", "Walder"]
const newList = [theList[theList.length - 1], ...theList.splice(0, theList.length - 1)]


    
// check output
console.log(newList)
// check output
console.log(theList)

Not ideal (unless you're Arya). Replacing splice with slice leaves the original array intact, and will not mutate it (which can lead to a mountain of problems):


    
const theList = ["Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn", "Walder"]


    
const newList = [theList[theList.length - 1], ...theList.slice(0, theList.length - 1)]

console.log(newList)
console.log(theList)

This leaves us with exactly what we want.

Another way to go about it is to use the Array.prototype.reduce-method, which to me feel a bit cleaner. Also, .reduce is worth investing time into learning.


    
const theList = ["Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn", "Walder"]


    
const newList = theList.reduce(
  (accumulatedArray, currentItem, index, originalArray) =>
    index < originalArray.length - 1
      ? [...accumulatedArray, currentItem]
      : [currentItem, ...accumulatedArray],
  []
)

console.log(newList)
console.log(theList)

This can, of course, be made into a function. Tempting as it may be, I don't recommend using an anonymous arrow (=>) function for this, as it doesn't show up with a name in the console stack trace if something wrong occurs:


    
const theList = ["Cersei", "Joffrey", "Ilyn", "The Mountain", "The Hound", "Melisandre", "Beric", "Thoros", "Tywin", "Meryn", "Walder"]


    
function shiftLastToFirst (theArray) {
  return theArray.reduce(
    (accumulatedArray, currentItem, index, originalArray) => {
      return index < originalArray.length - 1
        ? [...accumulatedArray, currentItem]
        : [currentItem, ...accumulatedArray]
    },
    []
  )
}
shiftLastToFirst(theList)

Now, I'm certain there are many smarter ways of doing this. And the reason I'm writing this up and putting it here is that I want to learn about them.

How would you go about solving this?

The problem with “you guys”

Knut Melvær — Wed, 12 Dec 2018 12:23:18 +0000

I made a bot that suggests some alternative phrasing when you write guys in Slack. It made for some discussion.

// Detect dark theme var iframe = document.getElementById('tweet-1072253704663912448-590'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1072253704663912448&theme=dark" }

I have seen in different Slack communities that people have implemented a Slackbot response that triggers whenever people write ”guys“, suggesting some alternatives that are considered more inclusive. It also links to an article in Vox about npm’s you guys-jar. A similar commentary was also published in The Atlantic that includes comments from a linguist. There's also a handful of threads on forums where people discuss whether the word "guys" is considered gender neutral or not.

Not surprisingly, not everybody was convinced by the bot’s legitimacy. I had a handful of people tell (on behalf of their English speaking part of the world) me that “guys” actually was gender natural (I am aware). Some went further and suggested that this was censoring and undermining the way they talked. It’s tempting to point out how many of them were not… guys. (well, none).

My tweet also gained a lot of likes and retweets, suggesting that some folks appreciated the idea, or at least wanted to be affiliated by what it signals. And this is taking us closer to the matter of hand. Because I'm all but sure that a “Guys bot” is the right approach to the problem we try to solve: How to make welcoming and inclusive communities in tech. I put it out partly as an experiment and to learn more by the reactions to it.

Nobody likes being told they're wrong

I have a lot of training in being wrong. I have spent years at university being told I'm wrong in all sorts of creative ways. Being open to being wrong is an essential part of learning and developing knowledge, especially in science. Still, I very often get defensive and moody when I'm told so. It's a very human response. It's something I have to actively work with.

The reason it’s irritating is that there’s often a moral dimension to it, that doesn’t align with whatever you intended. I bet that most people that greet a group with “Hi, guys!” don’t intend to be exclusive, but the rather opposite. When you’re instantly hit back with a canned response that suggests that this seemingly innocent way of speech may be considered hurtful to some, I have no problem in seeing that some might find that obtuse.

I suspect, though, that people who have a lived experience of not being included in all sorts of ways, in a field still dominated by mostly men, may have a more empathetic response because they get what the bot is trying to solve.

Bots lack nuance

There are good reasons to object to a bot automatically correcting language in a public community. To borrow the analogy from one of my colleagues, one wouldn't like having something that buzzed every time someone said it in the office space. Like in Demolition Man:

Since nor me or the originators of the Slackbot response have spent time tuning the algorithms, it also triggers on a lot of false positives. Which is somewhat counterproductive.

The reason a bot is tempting for community moderatos is that also lessens the chance that you end up in long-winded debates whenever you have to remind people of the Code of Conduct and telling them they’re wrong. Also, you can’t be everywhere at the same time. A bot can.

Why the bot stays (at least for a while)

None of those who have given me critique have been able to convince me to turn off the bot though. That’s mainly because the critique doesn’t come from a place of empathy, but is mostly self-affirming and resisting consideration of what we try to achieve (to be fair, some have also acknowledged what it tries to do, but it usually ends there).

Some are irritated that the bot corrects what they perceive to be a perfectly legitimate way of addressing a group, considered to be inclusive in their lingual context. And thereby telling me that I'm wrong, and perhaps because I'm not a native speaker (not seeing the irony).

For someone that spends most of their they day communicating in a second language (my native being Norwegian), I must admit my sympathy is lacking for someone who feels it though to adjust by one word. It’s also telling that they don’t consider English to be a highly diverse and multi-faceted language. And that we might have to take other considerations in an online multi-cultural community where gender bias is a proven issue than in one’s hometown.

It's not about you guys

I also suspect that some think of this bot as just another example of virtue signaling and political correctness. Recognized as hostile forces to the open and liberal mind by some. Most of those I’ve encountered that have made this their hill to die on aren’t really open to taking in other perspectives or entertain the motivations behind questioning how language can be used to include or exclude people. They do not ask me why I really did this, or what problem I try to solve. So although I find pointing out hypocrisy a lazy argument, it certainly doesn’t help their case.

So if you are a promoter of the open though and the free word, I'll ask you to reconsider the motivation behind efforts like this bot. For example by watching Patricia Aas’ talk Deconstructing Privilege. Or actually listening to the experiences of different underrepresented groups in tech (and elsewhere), and consider how being reminded that you don't really belong might affect your motivation to stay in web development, technology, or whatever you do.

Because you guys, it's not just about you guys.

Why I love working at Sanity.io

Knut Melvær — Tue, 11 Dec 2018 06:57:11 +0000

Four years ago I was a grad student with a Ph.D. fellowship in the Study of Religions, so how did I end up working for a tech startup? This is a post about how I, Knut Melvær, came to run Developer Relations at Sanity.io – it's also a celebration of following less obvious paths.

(Cover image: Me presenting Sanity.io on the Google stage at Slush, with Bjørge)

In 2015 I was getting worn down. Recruitment practices in the academy are harsh. The prospect of being passed from one temporary university teaching contract to the next wasn't very appealing either. My fellowship was nearing its end, and while I had both published peer-reviewed research, and done lots of teaching and dissemination – it was challenging working on a thesis using digital methods in a field with very, very little experience with such things. Also, I’d developed a severe depression – which, after a too long stretch, I sought help mastering, and am mostly OK from today (do get help people!).

A couple of months before my stipend ran out, I got a job offer as an interaction designer (which soon became “technology strategists”) at the wonderful, UX-oriented design agency Netlife. In addition to my tech-oriented humanities background, I was an experienced web development freelancer. But I was very lucky to get the offer as it not only meant I didn't have to constantly worry about earning a living and how to get the next contract, but I was welcomed to a milieu where people had each other’s back and cheered you on. Not too much of that in the academy. Not that I'm bitter. Or wait.

I worked at Netlife for three years and enjoyed every minute of it – although multiple concurrent clients with high demands, sometimes on tight budgets and with much at stake, also does take its toll.

So when I got the offer from Sanity.io to join as a developer advocate, it felt like a special opportunity. I would get to work on a special technology along with some very talented people. It felt like the right time to move on and an opportunity not to be missed.

I had already had the pleasure of working with Sanity as tech-lead when building Netlife’s new website, using it as a content backend, with Next.js as the frontend, and multiple Node.js-microservices on Heroku. We had also run the same setup for U4 Anti-Corruption Resource Centre. Those experiences inspired me to write the blog post “Headless in Love with Sanity”, which — though I didn’t get at the time — kinda ended up being my job application. Notwithstanding, the motivation was a real appreciation to be working with something where you felt a lot of care and thinking had gone into making my life as a developer easier, and frankly, more fun.

Now that I have been working at Sanity for half a year, I thought it was time to jot down some thought about why it has been such a blast. It’s also a not too subtle pitch for those of you who either are considering applying for a position – or are asked to join. That being said, my motivation to write this it is pretty pure and an opportunity to reflect on what makes my job meaningful and exciting.

The people

I, like many others working with technology in Norway, had an admiration the people behind Sanity for many years. They used to be a technology- and design agency called Bengler, with a track record for doing weird/challenging/state-of-the-art work, such as making a social network tied to local publishing, that launched concurrently with Facebook, controller software for 3d printers, a chorded text input device, or disruption-as-a-service toolkit.

Frankly, coming to work with these people would have been terrifying, if it weren’t that they are all incredibly pleasant, grounded, and open-minded. They challenge you when you haven’t thought properly through the implications of your suggestions, but also cheer you on when you ship. As one of the first “outsiders” in the new company, I have never felt excluded or not a part of the team. Of course, that may come from selection bias, but I would be surprised if the same didn’t account for new, and more diverse hires than myself (a Norwegian white male in his 30s). It's a startup with grown-ups, with families, obligations, hobbies, and things happening outside of work.

The product

At work, pretty much all of our attention is tied up in what we’re making: Sanity. I have done my fair share of CMS related development, be it Wordpress, Craft CMS, Statamic, Contentful, and others. Although it isn't fair to categorize Sanity as “just another CMS,” used as one, it has undoubtedly been the most fun one to work with (and Craft CMS is pretty darn fun). I believe it’s because Sanity.io opens you to so many possibilities. There are plenty of doors that open when you deal with a real-time backend, having a relational document store with a graph-oriented query language, with an open source React content editing app. This makes Sanity.io pretty unique and awesome – it took them years to build.

However, all the little things are as important: some minor functionality in the CLI, some available method on the way you can tweak the document listings or a feature in GROQ. I can’t count how many times I asked if you could do this or that, and while waiting for the answer, discovering that, yeah, you can do it. It's nice to stumble over exactly what you need when you need it. Using Sanity.io has been a series of such experiences.

Sanity is already remarkable in its own right, but looking at the very secret backlog, there are so many cool things that we can build on top of this stack, that I can’t even. 2019 will be an exciting year, for sure.

The community

I have been mistaken so many times since I started in Sanity – which to me, is part of the appeal (that means that I’m learning). One thing I was very wrong about, was my worry about launching the community platform. I was so ready to have to moderate and deal with trolls and hostile people in our community Slack. I was very wrong.

It has been such a joy to get to know our community, get to answer surprisingly challenging questions (because people are using Sanity to solve challenging things), take very constructive feedback, and — this is my favorite thing — see the stuff people are building. The community has grown very fast, but it hasn’t been a single instance of harassment or bad behavior (as far I have been able to gather). As we continue to grow, a key concern is to make everyone feel welcome and included.

The office space

I go to work to the coolest office (though the floors are heated). Almost every day (as a commuter I treat myself to the home office once in a while), I enter a converted horse tram depot at Grünerløkka, a lively neighborhood in central Oslo (the capital of Norway). It’s an open space, yet it doesn’t give the feel of an open office. Behind where I tend to sit, there is a workbench where Polarworks (which also grew out of Bengler) are developing super cool motion control software. It very much feels like a maker space. So although I’m not that into beer and aware that it makes us sound like outtakes from Portlandia, it is indeed nice to have a micro-brewery where good tasting brews are made. Next year we'll be opening an office in San Fransisco, that'll be exciting too!

From one of our meetups

The challenges

To me personally, the primary motivation that brings me to work every day is many challenges of working on a product like Sanity, which both has many features, but with the ethos of being super easy to use. We sincerely believe Sanity has a place for developers that need a backend for structured content – be it a weekend project, or for enterprise needs. To take a product out in the world is hard work. To prepare your organization for taking on more people is always a challenge. To understand what’s truly useful for people, and how to communicate with them, is not easy. To take time off to recuperate and get enough brain air to stay creative can be difficult when crazy-stuff-we-can’t-talk-about-yet™ is happening every week. To be allowed to be wrong, to experiment, and given the trust to try stuff I haven't really done before are sometimes scary, as there is a great deal of responsibility that goes into it.

However, those are also the things that drive me, and why I, frankly, love working for Sanity.io. I hope I get to share that pleasure with you some day.

I should also mention our office dogs, my own Jara, and Espen’s Kokos. 📸 Even Westvang

Jara

Kokos

Creating Custom Content Blocks: Wordpress Gutenberg vs. Sanity.io

Knut Melvær — Fri, 07 Dec 2018 07:38:19 +0000

Wordpress 5.0 comes with a brand new rich text editor called Gutenberg. It is highly anticipated and has created both buzz and controversy. The promise of Gutenberg is customizability, especially when it comes to adding custom content blocks. If you want to get started with Gutenberg, you can read this excellent introduction in Smashing Magazine. It is built in React and allow developers to extend the editors basic functionality.

Custom testimonial block type in Wordpress Gutenberg. Published on smashingmagazine.com

We couldn't resist though. Since having custom content blocks is in the DNA of Sanity, we wanted to show how easy it is to recreate the testimonials slider that the 12 min read, and 10 part article introduces you to. Like an eleventh of the time easier. 🐇

Of course, the comparison only goes so far. Wordpress is a classic CMS with a template engine, whereas you can use Sanity as a headless CMS with the frontend framework you would prefer, be it Vue, React or something else.

If you haven't tried Sanity yet, it only takes two minutes to get started. To create a project and get an instant real-time hosted content API, and the connected open sourced editor locally, run this line in your terminal:

    npm install -g @sanity/cli && sanity init

If you choose the blog template in the CLI tool, you're pretty much set to go!

The testimonial slider content model

In the tutorial on Smashing Magazine, you learn to make a "testimonial slider" – typically used on marketing pages as a way to visualize social proof for your product.

To re-create the Wordpress testimonial slider for Sanity you only need to define its content model. We'll take care of the input fields, and the real-time syncing to the datastore.

The content model is pretty straightforward: First, we make the type for a testimonialSlider. It's an object, with an array (which also holds the order of the testimonials) of testimonial objects with the fields author, image, content, and link to the source. I made the content field be clean text, but we could also have used blockContent if we wanted to have rich text (and a slider within a slider, in case you are into recursive content patterns). If we add options: { hotspot: true } to the image field, your editor can even set custom hotspots and crops for the image, which may be useful for image art direction.

 const testimonialSlider = {
  name: 'testimonialSlider',
  title: 'Testimonial slider',
  type: 'object',
  fields: [
    {
      name: 'slider',
      title: 'Slider',
      type: 'array',
      of: [
        {
          name: 'testimonial',
          title: 'Testimonial',
          type: 'object',
          fields: [
            {
              name: 'author',
              title: 'Author',
              type: 'string'
            },
            {
              name: 'image',
              title: 'Image',
              type: 'image'
            },
            {
              name: 'content',
              title: 'Content',
              type: 'text'
            },
            {
              name: 'link',
              title: 'Link',
              type: 'url'
            }
          ]
        }
      ]
    }
  ]
}

const blockContent = {
  name: 'blockContent',
  type: 'array',
  of: [
    {
      type: 'block'
    },
    {
      type: 'testimonialSlider'
    }
  ]
}

export default {
  testimonialSlider,
  blockContent
}

That's pretty much it. The user interface will be clean and can be used right away.

To get that nice prepared JSON-structure for your frontend, you can use this GROQ query, assuming that your rich text is named content and used in the document type post:

*[_type == "post"]{
  ...,
  content[]{
    ...,
    _type == "testimonialSlider" => {
      slider[]{
        ...,
        image{
          ...,
          asset->
        }
      }
    }
  }
}

Custom preview component

You can also add a custom preview component with some React code:

import React from 'react'
import client from 'part:@sanity/base/client'
import urlBuilder from '@sanity/image-url'
const urlFor = source => urlBuilder(client).image(source)

const sliderPreview = ({ value = {} }) => {
  return (
    <marquee>
      {value &&
        value.slider.map(slide => (
          <div
            key={slide._key}
            style={{ display: 'inline-block', marginRight: '1em' }}
          >
            <figure>
              <img
                src={urlFor(slide.image)
                  .width(50)
                  .url()}
                style={{ marginRight: '0.5em' }}
              />
              <span className="legend">
                “<em>{slide.content}</em>”<br />
                {slide.author} – {slide.link}
              </span>
            </figure>
          </div>
        ))}
    </marquee>
  )
}

export default sliderPreview

Include it in your schema by adding this to your testimonialSlider content type schema:

import React from 'react'
import sliderPreview from './sliderPreview.js'

const testimonialSlider = {
  name: 'testimonialSlider',
  title: 'Testimonial slider',
  type: 'object',
  preview: {
    select: {
      slider: 'slider'
    },
    component: sliderPreview
  },
  fields: [
    /* the fields */
  ]
}

Here I've used the good old HTML element <marquee> to get a scrolling effect; you probably shouldn't do the same:

Beyond appearances: The advantage of deeply typed rich text content

This testimonial slider example tightly ties to a specific presentation on a webpage, which makes sense in WordPress because it's built to render and manage a website. WordPress saves the input in Gutenberg as HTML, which is what you eventually also get out of the APIs. HTML in content APIs is generally not what you want if you want to use it in your favorite frontend framework, or in something that should render in something other than a web browser.

Sanity saves the content in the editor as Portable Text, which makes it portable across any markup, but also makes rich text queryable. It should be easy to create custom editorial experiences, with the custom types and inputs that makes sense in your project or organization, and it should be easy to take that content and fit it to whatever form of presentation.

Get started with the Mux video plugin

Knut Melvær — Sat, 01 Dec 2018 09:23:15 +0000

When building Sanity, we placed much emphasis on building out a super flexible image pipeline that can transform and re-crop your images for you. We have no ambition of doing the same for video.

When Mux reached out to us about integrating with their video streaming and analytics platform we had no doubts that it would be a good fit.

Who is Mux?

Mux was founded in 2015 by Jon Dahl, Steve Heffernan, Matt McClure, and Adam Brown. Jon and Steve were the co-founders of Zencoder, which got acquired by Brightcove. With a team of engineers from YouTube, Twitch, Brightcove, and Facebook, they're now leading one of the best cloud-based video services on the web.

Mux is an API-first video platform for streaming and analytics. What sets them apart is their self-optimizing encoding and delivery technology. The service provides high-quality streams for your users that adapt to device, and network conditions. What you also get is transparency on how your videos perform. Mux makes this easily accessible with Mux Data, which gives you detailed video performance metrics – in real-time.

The performance and functionality of Mux are excellent. Store your full resolution master file with Mux and request whatever format you need – HLS for streaming, MP4 for downloads. Even GIF if you need it. From your frontends, apps, and digital services you can request exactly the format you need.

Get started with the mux-video plugin

The Mux plugin for Sanity gives you a way to upload and preview videos easily.

Installation

Run this command in your Sanity project folder:

Use in Schema

To use the Mux video input, you create a field as you otherwise would, and use mux.video for the type.

    export default {
      name: 'catVideos',
      type: 'mux.video'
    }

Add API keys

Register for Mux (if you tell them "sanity" they'll give you $50 worth in credits ✨). If you don't yet have a project on Sanity - we've made a special offer also.

The token needs full access to upload files

Once you're logged in to Mux, find the "Access Tokens" page in the settings menu. Generate new tokens with full access **on Mux Video and Read **on Mux Data, and have them handy for the next step.

Back in Sanity Studio, find the document where your video field appears, and click the plug-icon 🔌on the Paste your Access Token and Secret Key.

Enter your Mux API credentials

Uploading a video

Uploading a video is easy: Use the select button to open the file explorer on your system, drag the file right into the input area, or paste the URL (like I do in the video) to the video in the field. Once it's done uploading, you can select the thumbnail you want for the preview. Check the video in the codesandbox to see how it works.

Querying it with GROQ

In this example, we have added the Mux video as a custom block in rich text. We can then use GROQ to generate the URL for the stream on the frontend. Here we also use concatenation to get the streaming URL out of the box.

    [*_type == "post"]{
      ...,
      text[]{
        ...,
          _type == "muxVideo" => {
            ...,
            asset->{
                ...,
                "url": "https://stream.mux.com/" + playbackId
                }
            }
        }  
    }

If we pick out the asset data from the response to this query, we'll get something like this:

    {
      "_key": "121c8c30a649",
      "_type": "muxVideo",
      "asset": {
        "_createdAt": "2018-11-30T18:27:21Z",
        "_id": "066e45f9-e2e6-4537-8b40-05f8c0f334d9",
        "_rev": "0xLJdqcI4pgly0b1J2cj0o",
        "_type": "mux.videoAsset",
        "_updatedAt": "2018-11-30T18:27:27Z",
        "assetId": "KdUXsmAKryppWd1wPiAtNVhMIqc7cPmL",
        "data": {
          "aspect_ratio": "16:9",
          "created_at": "1543602441",
          "duration": 28.233333,
          "id": "KdUXsmAKryppWd1wPiAtNVhMIqc7cPmL",
          "master_access": "none",
          "max_stored_frame_rate": 30,
          "max_stored_resolution": "HD",
          "mp4_support": "none",
          "passthrough": "066e45f9-e2e6-4537-8b40-05f8c0f334d9",
          "playback_ids": [
            {
              "id": "NZQMBbYtVa6pDebOjB8wXRNQvao3RWrv",
              "policy": "public"
            }
          ],
          "status": "ready",
          "tracks": [
            {
              "duration": 28.142585,
              "id": "Tcte02pHV5iGVYDUqGX5hiT5XqgB8pMym",
              "max_channel_layout": "stereo",
              "max_channels": 2,
              "type": "audio"
            },
            {
              "duration": 28.166,
              "id": "ocguJveQvPh95zPcnuitsLLXvLYaTAMwPfgDoqFLD01Q",
              "max_frame_rate": 30,
              "max_height": 1080,
              "max_width": 1920,
              "type": "video"
            }
          ]
        },
        "filename": "upload video with mux.mp4",
        "playbackId": "NZQMBbYtVa6pDebOjB8wXRNQvao3RWrv",
        "status": "ready",
        "url": "https://stream.mux.com/NZQMBbYtVa6pDebOjB8wXRNQvao3RWrv"
      }
    }

As with our image pipeline, we make sure to have the metadata readily available. This means that you also easily can query for video assets by all these keys. For example will the query [*_type == "mux.videoAsset" && data.aspect_ratio == "16:9"] return all uploaded videos with a letterboxed aspect ratio.

Video playback on the frontend

The final piece of the puzzle is to get your videos to your end users. You can integrate videos on Mux with all sorts of stuff, be it the web, apps, TV platforms, or even offline by providing your users with an mp4-download. We made a video player for React that is easy to integrate into your project. Check it out on GitHub or in the CodeSandbox beneath.

First class video support

We're super happy that Mux reached out to us, and that we get to stand on their shoulders when it comes to video support. We are planning to improve the integration even further, and we're stoked to see what you will make with it. For a more technical and in-depth read about integrating Mux on web frontends, do check out the blog post by our friends in ZEIT, who just launched their new platform ZEIT TV using Mux.

And finally, a cat video. Because everyone should have at least one cat video in their video archive.

Source