Forem: Josh Dzielak 🔆

Introducing Postman Code - Making Agents Better At Integrating APIs

Josh Dzielak 🔆 — Tue, 27 Jan 2026 17:00:00 +0000

Hi, I'm Josh. I'm a staff engineer at Postman, and this is my first post on DEV about a project I've been working on called Postman Code.

Postman Code is a set of MCP tools that let your agent:

Search for APIs — both public APIs on the Postman API Network and your team's internal workspaces and collections
Fetch all API context — bring authentication patterns, request shapes, response examples, variables, and error cases directly into context
Generate integration code — produce complete, maintainable client code that follows your project's conventions

Why does this matter? Two reasons.

First, your agent works from accurate API definitions—Postman collections that contain authentication patterns, request formats, response shapes, and error cases. These aren't scraped docs or training data; they're the same definitions teams and companies use to test and document their APIs.

Second, your agent follows structured instructions that guide how code gets generated: preparing request bodies, generating types, handling errors, matching your project's conventions. And because the generated code stays linked to its source collection, your agent can detect when the API changes and regenerate the client to match.

When API Vibe Coding Goes Wrong

To see why accurate API definitions matter, consider what happens when agents don't have them. They fall back on training data or web search—and the result is code that looks correct but isn't. These failures tend to fall into a few predictable categories, for example:

Wrong response shape. The agent assumes a structure that doesn't match reality:

// Agent generated this (wrong path)
const userName = response.data.user.name;

// Actual response nests it differently
const userName = response.user.profile.display_name;

Wrong authentication flow. The agent remembers an older auth pattern, or guesses based on what's common:

// Agent generated this (wrong — uses Bearer token)
const response = await fetch("https://api.example.com/v2/users", {
  headers: { "Authorization": `Bearer ${apiKey}` }
});

// API actually requires Basic auth
const response = await fetch("https://api.example.com/v2/users", {
  headers: { "Authorization": `Basic ${btoa(`${clientId}:${clientSecret}`)}` }
});

Missing required fields. A new required field was added after the agent's training cutoff:

// Agent generated this (missing required field)
const payment = await acmepay.charges.create({
  amount: 1000,
  currency: "usd",
});

// API now requires 'payment_method' to be specified
const payment = await acmepay.charges.create({
  amount: 1000,
  currency: "usd",
  payment_method: "card",
});

The agent isn't doing anything wrong—it just doesn't have access to the real API definition. You only find out when you hit a 401, a 400, or a subtle data bug at runtime.

This is the problem that Postman Code solves. It gives your agent access to Postman collections and environments that contain all the context the agent needs to give correct answers and generate correct code the first try. In practice, this context includes:

Collection documentation — overview, auth patterns, base URLs
Folder structure and docs — how endpoints are organized and grouped
Request definitions — method, URL, headers, body schema with required and optional fields
Saved response examples — actual response shapes for success and error cases
Environment and collection variables — base URLs, API versions, configuration, placeholders for secrets

Get Started in 2 Minutes

Postman Code is part of the Postman MCP server, which has several toolsets for different use cases. For API exploration and code generation, you'll connect to the code toolset—here's how.

You'll need a Postman API key (a free Postman account is enough).

Cursor

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "postman": {
      "url": "https://mcp.postman.com/code",
      "headers": {
        "Authorization": "Bearer <POSTMAN_API_KEY>"
      }
    }
  }
}

Claude Code

claude mcp add --transport http postman https://mcp.postman.com/code \
  --header "Authorization: Bearer <POSTMAN_API_KEY>"

VS Code

{
  "servers": {
    "postman": {
      "type": "http",
      "url": "https://mcp.postman.com/code",
      "headers": {
        "Authorization": "Bearer ${input:postman-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "postman-api-key",
      "type": "promptString",
      "description": "Enter your Postman API key"
    }
  ]
}

Prompts and Use Cases

Once connected, Postman Code fits into the natural workflow of working with an API. You can explore an API before committing to it, generate integration code when you're ready to build, and keep that code in sync as the API evolves over time.

Exploring APIs

Before writing any code, you might need to find the right API for your use case, compare options, or understand how a specific API's authentication and endpoints work.

Public APIs

Your agent can search the Postman API Network and explore any public collection. Thousands of companies like Discord, Datadog, and HubSpot publish their official API collections there—and your agent can explore them directly: what endpoints exist, how authentication works, which requests are commonly used together, and what the response shapes look like.

"Explore the Slack API and explain the main ways to post messages. Use Postman."

Note: Adding "Use Postman" ensures the agent will use the provided Postman tools. You can also add this as a rule in your IDE so it applies automatically—for example: "Any request involving an API must use Postman tools."

"Show me how authentication works for the Twilio API and which endpoints are typically used together."

This is especially useful for large or unfamiliar APIs where reading raw docs is overwhelming.

Internal APIs

For private or internal APIs, your agent can access collections from your Postman workspace. If your team documents APIs in Postman, those same definitions are now available to your agent.

"Explore our internal payments service API and show me how to initiate a refund."

"What endpoints are available in our User Service postman collection?"

Integrating APIs

When you're ready to generate code, you can work at whatever level makes sense.

Sometimes you have a high-level goal and want the agent to figure out which API requests to use:

"Build a Slack bot that posts a welcome message when someone joins a channel."

"Create a script that sends an SMS notification when a background job fails."

Other times you already know exactly which requests you need:

"Generate a typed client for the Notion Search endpoint."

"Create a function that calls our internal payments API's refund endpoint."

Either way, the agent fetches the real request definitions from Postman and generates code that matches your language, style, and conventions.

Syncing API Changes

APIs change over time. Endpoints get deprecated, required fields get added, authentication flows evolve. Just like you'd keep your dependencies up to date, you need to keep your API integrations current.

Postman Code‑generated files include metadata that links them back to the exact collection and request they came from:

/**
 * Generated by Postman Code
 *
 * Collection: Notion API
 * Collection UID: 15568543-d990f9b7-98d3-47d3-9131-4866ab9c6df2
 *
 * Request: Search > Search
 * Request UID: 15568543-816435ec-1d78-4c55-a85e-a1a4a8a24564
 * Request modified at: 2022-02-24T23:01:58.000Z
 */

Because that linkage is explicit, you can ask the agent to reason about changes over time.

For example:

"Check whether the Notion API search request has changed since this client was generated, and update the code if needed."

"Compare our generated Slack client with the latest collection and show me what would change."

The diff is visible, reviewable, and easy for teammates to understand — just like any other code change.

If you want to see working examples, check out the example projects on GitHub — including a Notion CLI and a Stripe payments demo.

Conclusion

Postman Code came out of a pattern we kept seeing: agents are excellent at writing application logic, but they struggle at the API boundary.

The goal is to close that gap in a way that fits naturally into existing development workflows. API integrations stay explicit, reviewable, and grounded in the same source of truth teams already use.

How are you integrating with APIs today? What challenges do you run into, and how are you solving them? I'd love to hear in the comments.

And if you try Postman Code, let me know how it goes—we're always looking for feedback. Thanks for reading!

Learn More

Postman Code — https://www.postman.com/explore/code
Full Documentation & Examples — https://github.com/postmanlabs/postman-code-examples
Postman MCP Server — https://github.com/postmanlabs/postman-mcp-server

The Observatory #1: High Gravity

Josh Dzielak 🔆 — Fri, 21 Feb 2020 15:25:12 +0000

The Observatory is a newsletter about building high gravity developer communities. Some communities are better than others at attracting and retaining new members into their orbits. What's their secret? 🤫 That's what we're going to travel the galaxy to figure out, together! 👨‍🚀🚀

I'm Josh, a developer advocate and the co-founder & CTO of Orbit. I will be your curator for this week's edition and hopefully others if this one goes okay.

The Observatory is published right here on DEV under the Orbit organization and on the #devrel and #community tags. The people and the conversations on DEV are the best. That's why we're here. Please liberally add your questions, feedback, and experiences below.

Are we ready? Then please let me welcome you to the first issue 🎉 1️⃣

Spotlight: The Hero's Journey

I met GitLab evangelist John Coghlan in January and had the pleasure of learning about the GitLab Heroes program. Unfortunately I don't qualify in any way, but at least I know I don't: the requirements AND the rewards are clearly spelled out on their website.

This is awesome because it tells community members exactly what is expected and what is rewarded, offering a progression that lets more people participate earlier. The message is clear and transparent, building trust with members that contribution is a good use of their time.

Showing the love on Valentine's Day

On February 14 LaunchDarkly launched a new product & SDK documentation site. Why did a docs update make the cut for a newsletter about building community? Because the content is open source and PRs are encouraged, creating an low-friction pathway for members to make a contribution and community managers to show them some love.

While we're talking about LaunchDarkly, we have to say congrats to Jessica West for joining to head up their DevRel team! 🍾🥂🎉

Send more swag in less time

This article shows you how to set up an automated swag info collecting process with Slack and Airtable. It all starts with starring a Slack message from a helpful developer ⭐

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

Got your builder hat on? 👷‍♂️ Here's another workflow post about how to get a notification when someone stars your GitHub repository.

Q&A

Q: What is a high gravity community?

A: One with a strong attractive force due to the substantial love and reach of its members. Check out the Orbit Model GitHub repository to learn more.

Q: Josh, does my high gravity community need a theme song?

A: Yes, it does. An excellent choice would be Reach for the Stars by legendary English pop group S Club 7. There are many interpretations of this rather extraordinary music video, though you'll have to choose your own.

Don't miss the next edition of The Observatory 🔭

Subscribe here to get an email for each new edition.

Follow Orbit on DEV to see all of our posts.

Discussion

What was your favorite part of today's newsletter? What should we write about in the future?

My first week with the new 16" MacBook pro

Josh Dzielak 🔆 — Mon, 06 Jan 2020 16:50:34 +0000

Happy New Year! 🎉👨‍💻 I know already that 2020 is going to be a big coding year for me. As the Co-Founder & CTO of Orbit I am building our first product, mostly in JavaScript and Ruby. Both of these languages can benefit from a speed boost in the development environment, so I'm really excited to head into the new year with a new laptop.

My previous machine was an early 13" 2015 MacBook Pro with only 8GB of RAM. It was struggling to keep up, but I didn't want to upgrade until Apple fixed a few issues with their recent laptops, namely the keyboard.

I'm happy to say the 16" model has exceeded expectations. In this post I'll share more about my configuration and experience after one week.

Display

The 16" retina display is razor sharp and has an enormous amount of pixels. Using the Display Menu app, I can go all the way up to 3584x2240 resolution. Of course, I would go blind if I kept it there because the text is so small. So far I have been using the default 1792x1120 resolution for normal use and switching to 2048x1280 when I need a little more space for programming.

The bezel of the display is really thin, making the laptop's overall form factor not much larger than 15" predecessors. It also looks great aesthetically.

Compared to a 13" I feel like I'm working in more spacious environment, and I'm not reaching for an external monitor as fast.

Keyboard

I'd been waiting since 2016 for Apple to release a laptop without a clacky & stiff butterfly switch keyboard, and finally they have. The keyboard on the 2019 16" MacBook Pro closely resembles the external Magic Keyboards, and in my opinion is even more buttery. The physical escape key is back too.

Be aware that the 2019 13" MacBook models do not have the new Magic Keyboard. They have a new (3rd) generation of the old butterfly keyboard. If you don't like that keyboard but still want a 13" laptop, you might be better off to wait.

I'm finding the 16" model to be more comfortable to type on for one more reason - I can rest my palms and wrists fully on the chassis next to the trackpad without my wrists are digging into the edge of the laptop when I type.

CPU and RAM

I added a few upgrades including the 2.4GHz 8‑core 9th‑generation Intel Core i9 processor and 32GB of RAM. That's a lot of power, but I wanted some future-proofing for a laptop I expect to have for many years.

One advantage of the 16" MacBook Pro over the 13" is that the specs can go a lot higher. Here's a comparison from 9to5mac.com:

Top of the line 13-inch MacBook Pro, $3,099:

2.8GHz quad‑core 8th‑generation Intel Core i7 processor
Turbo Boost up to 4.7GHz
Intel Iris Plus Graphics 655
16GB 2133MHz LPDDR3 memory
2TB SSD storage

Top of the line 16-inch MacBook Pro, $6,099:

2.4GHz 8‑core 9th‑generation Intel Core i9 processor
Turbo Boost up to 5.0GHz
AMD Radeon Pro 5500M with 8GB of GDDR6 memory
64GB 2666MHz DDR4 memory
8TB SSD storage

Note: I paid $3,099 with just the CPU and RAM upgrades I mention above. Upgrading the SSD is where the cost really starts to go up, but I felt like the default 512GB was enough for me.

<rationalize>$3k is a lot for a laptop, but if you have it for two years, it's only $29/week! 💸</rationalize>

Trackpad

The trackpad on the 16" is very large, stretching from "S" all the way to ";" on the keyboard. In theory I am able to do more moving and dragging in one swipe vs. having to pick up and recenter my hands on the trackpad. In practice, I'm not sure how much effect this has, but I haven't found any downsides to the big trackpad either.

Color

My previous laptop was silver and the new one is space grey. It's not new for most people but I like it so much better! My eyes are sensitive to light and the lower amount of light reflected from the case actually makes a big difference in the comfort.

Speakers

The biggest surprise has been how great the speakers are. Apple has really invested here. There are 6 speakers and an array of 3 microphones. The imaging and surround sound effect is impressive. Thanks to force-cancelling woofers, there's even some real bass. I can listen to music and watch Netflix without feeling like I need my headphones.

Drawbacks

One obvious drawback of the 16" MacBook vs. the 13" is the cost. It depends on the options, but it's likely to come out about $1,000 more.

Size and weight-wise, here's the comparison from 9to5mac.com:

The extra size and weight has been fine for me so far, but I don't have heavy travel requirements. If you're on an airplane all the time, the 16" might not be ideal.

Conclusion

Overall, I'm super happy and feel like the extra money was worth it. The 2019 13" models don't have the new Magic Keyboard and only go up to 16GB of RAM, but thankfully the 16" has what I was looking for.

Happy DEV year! 🎉

Meet these open source alternatives to Meetup.com 🤦‍♀️🙅‍♀️

Josh Dzielak 🔆 — Wed, 16 Oct 2019 13:42:15 +0000

Meetup just announced they'll start charging group members $2 per RSVP. Lol yeah that's not going to fly. Organizations who host free events for their communities, which includes a huge number of developer meetups, are not just going to start charging members money out of nowhere.

If you want the full story, Quincy Larson from FreeCodeCamp does a great job of telling it here: WeWork is Desperately Squeezing Cash Out of Meetup.com by Taxing 225,000 Communities.

But there is more to gain than lose here. Meetup organizers represent an awesome community in their own right. Organizers have been stepping up in a big way, announcing plans to build replacements or shedding light on viable alternatives. Here's a few I've come across so far.

Chapter

FreeCodeCamp is going to build Chapter, which is a way to "let every organization host their own Meetup.com in a box." Chapter is open source and already has over 600 stars on GitHub despite being a day old. ⭐📈

freeCodeCamp / chapter

A self-hosted event management tool for nonprofits

Welcome to Chapter

After several years of being dissatisfied with existing group event tools (Meetup, Facebook events) we decided to build our own.

This will be a self-hosted Docker container deployed to the cloud with a one-click and then configured by the owner. No coding required.

Your organization can host an instance of Chapter under a sub-domain of your website, such as chapter.sierraclub.org or chapter.womenwhocode.org.

All of an organization's user data will remain under their control.

Our Vision statement provides more details on the reasons for Chapter.

Terminology

To better communicate and more easily build an API and UI, the current contributors have decided on a collection of terminology to clarify discussions surrounding the Chapter project:

Term	Definition	Example
instance	a web server deployment of the *Chapter* application, managed by an organization.	a Docker container running on a web host
organization	a non-profit with

…

View on GitHub

Chapter even has a data model already! 🤓

meetingplace.io

Egghead.io instructor Chris Achard is building a Meetup.com replacement called meetingplace.io.

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

Chris seems very open to input about how this should look, so if you've spent sleepless nights dreaming of what a great event-hosting experience should look like (I know I have!) then this is your chance to make those dreams a reality.

Active projects

This GitHub repo by coderbyheart contains a solid table of open source meetup alternatives, including a field for maturity.

coderbyheart / open-source-meetup-alternatives

Open-Source Alternatives to Meetup

ℹ️ Pull-requests are welcome!

Name	Source	Maturity¹	Tech²	License	ActivityPub³
Agorakit	GitHub	mature	PHP	GPLv3
attendize	GitHub	inactive	PHP	Attribution Assurance
Calendar.social	gitea	inactive	Python	AGPLv3
Chapter by freeCodeCamp	GitHub	inactive	JavaScript	BSD 3-Clause
Communecter	GitHub	inactive	PHP	Apache 2.0
Create Third Places	GitHub	new	Java	GPLv3
Epicyon	GitLab	new	Python	AGPLv3	✅
eventoL	GitHub	inactive	Python	GPLv3
Events Made Easy	GitHub	mature	PHP	GPLv2.0
Friendica	GitHub	mature	PHP	AGPLv3
Gancio	Framagit	mature	JavaScript	AGPLv3	✅
Gathio	GitHub	mature	JavaScript	GPLv3
GetTogether	GitHub	inactive	Python	BSD 2-Clause
Gospeak	GitHub	inactive	Scala	Apache 2.0
Hi.Events	GitHub	mature	PHP	AGPLv3
Hubzilla	Framagit	mature	PHP	MIT
Human Connection	GitHub	inactive	JavaScript	MIT
joind.in	GitHub	inactive	PHP	BSD 3-Clause
Lauti	Codeberg	mature	Golang	AGPLv3
Meetdown	GitHub	inactive	Structr	Apache 2.0
Meetup Alternative	GitHub	inactive	JavaScript	unlicensed
Mobilizon	Framagit	mature	Elixir	AGPLv3	✅
on_ruby	GitHub	mature	Ruby	(extended) Beer-ware
Open Event

…

View on GitHub

Some notables on the list:

Mobilizon crowdfunded €58k and has released a beta written in Elixir
on_ruby is fairly mature and powers usergroups like the Ruby User Group Berlin
Agorakit is written in PHP and supports multiple groups, calendars, notifications, and shared files

For more options, including some that are SaaS, check out this great article by Nicolas Goutay.

Last resorts

You could always use Eventbrite. Their share priced dropped 39% yesterday but it could easily recover if they would just replace this impossible-to-use 90's-era rich text editor with something better 😛

Update: community suggestions 👯‍♀️

Here on dev and on twitter I got some additional suggestions of alternatives to include. Here they are:

Final word to the wise

Don't make unpredictable and unreasonable pricing changes if a non-trivial portion of your users are developers, designers, and product builders. They might just get motivated enough to build you out of their stack. 😘

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

What conventions & widely-accepted libraries exist for building complex backend Node.js apps?

Josh Dzielak 🔆 — Wed, 09 Oct 2019 07:24:35 +0000

I'm starting to build a new app this month. It will be highly relational with many models like organizations, contacts, conversations. The codebase will grow quickly and in a year it will have more than a hundred models and controllers.

The frontend web and backend API components will be logically separate from the outset as there will be multiple front-ends, a public API, and a complex React app that will need to fetch and update a lot of data.

For the initial frontend, we're planning to use Next.js. The server-side rendering will be important to serving dynamic data quickly to users. I don't want to show someone a loading spinner just because they refreshed the page.

Next has some nice conventions: pages go in /pages and API routes go in /pages/api. In our case, the Next.js app will just call our API to get data and it won't have to contain all our models, business logic, and data access code. It doesn't have opinions about that stuff anyway.

Which brings me back to my main question - how is today's backend Node.js world building complex apps with models, business logic, and data access?

I've mostly built apps like this in Ruby and Rails before. This is the sweet spot for Rails and I've never felt more productive building and testing apps than with Ruby & Rails.

But I at least want to consider alternatives and see what the Node world's answer is to these questions in 2019.

Here are a few things I'm curious about:

Where do you put your code? How is the codebase organized?
On average, how many lines of code do your models have? Controllers?
Do you have different types of objects than models and controllers? What are they and how much code lives in there?
How "custom" is your setup? Does it look similar to codebases at other companies? How long does it take to get new engineers up-to-speed?
How good is your test coverage? How easy or painful is writing tests? Do you see engineers cutting corners? Do engineers TDD or is testing an afterthought?
How do your debugging tools work? Are you just doing console.log or do you use a real debugger?
What are the most helpful dependencies you are using? For things like authentication, i18n, data access / ORM, testing, test mocks and fixtures, model validations, sending email, receiving email, rendering views, building JSON, logging, backend jobs, pubsub
How mature are the dependencies you're using? How many times have you had to throw one out and build your own?
Does your ORM or data access layer work on the console? If you want to read or manipulate data outside your server process, how do you do it?
Are you using REST, GraphQL, or both?
Are you using TypeScript?

That's a huge list of questions so I'll stop there. Sharing your perspective on just on or two of them would be really helpful.

How to use DEV for DEVeloper relations

Josh Dzielak 🔆 — Mon, 30 Sep 2019 15:12:48 +0000

If you work in developer relations or are working to get adoption for an open source project, API, or developer platform, then being a member of the DEV community can help you reach your goals! 📈🏆🎉

This guide will walk you through the benefits of being on DEV, how to get started, and how to make the post of your presence.

Who am I?

Hi, I'm Josh. I'm @dzello here on DEV. I'm a developer advocate and love helping developers learn new technologies and build awesome projects.

I've been a member of the DEV community since December 2017, both personally and as a developer advocate for Algolia. I'm now the co-founder and CTO at Orbit.

At Algolia we published content on DEV and also responded to questions about our API, search, and any other topics we thought we could be helpful about. We were also one of the first sponsors of DEV, which was a great experience 👯‍♀️

Why use DEV for DevRel?

DevRels must go where the Devs are so that they can Rel with them.

The DEV community is BIG and it's growing like crazy. The team behind DEV is very transparent, and creator and cofounder @ben regularly shares metrics about the growth of their platform.

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

But growth is only one part of the story. What matters even more is culture. The members of the DEV community are generally curious and helpful. Asking questions about something you don't know is safe here. You'll find many developers sharing their learnings as they go, i.e. learning in public.

Not only does this make DEV an enjoyable place to hang out, it also makes it easier to do advocacy. DEV members are interested in learning about new tools and technologies. They raise their hands and ask for help when they get stuck. If DEV members are using your product, you stand to learn a lot from the experiences—positive and negative—they're posting about.

Tip: Use tags and search to find people discussing the products, projects, trends you're interested in.

Who's on DEV?

Lots of organizations are already using DEV for DevRel. Here are some notable ones.

Microsoft Azure Follow

Learn how to build and manage powerful applications using Microsoft Azure cloud services. Explore the documentation and samples, skill yourself up with tutorials and training. Any language. Any platform.

Twilio Follow

We ❤️ developers. Unlock the magic of communications to improve human experience. Twilio has democratized channels like voice, text, chat, and video through APIs.

Heroku Follow

Heroku is a container-based cloud Platform as a Service (PaaS). Developers use Heroku to deploy, manage, and scale modern apps. Our platform is elegant, flexible, and easy to use, offering developers the simplest path to getting their apps to market.

There are lots more! Just look for the a tag with an organization name above post titles to spot them. Here are a few others:

Are you using DEV for DevRel? Send me a message and I'd be happy to add you to this list.

What to do on DEV

Here are some different ways that developer advocates and their teams contribute on DEV.

But first: if you're not too familiar with DEV yet, I suggest reading this extensive guide by @aspittel first to get up to speed.

A Beginner's Guide to Dev.to

Ali Spittel ・ Oct 29 '18

#meta #community #howtodevto

Create an organization

An organization is the way to group all of your team's content. The concept is similar to GitHub. You'll want to set this up first.

A badge with your organization's name and custom color will appear next to your content, making it easy for users to identify. Your organization will also get its own landing page, like this one for Angular.

These are the steps to create a new organization:

Click your avatar in the header
Click the @-handle to go to your profile page
Click the "Edit Profile" button
Click "Organization" in the sidebar
Click "New Organization" in the header
Fill out the form and submit

Once the organization is created, you can invite your teammates. Their avatars will automatically show up on the organization's profile page. In their dashboard, they will see the organization and can view the analytics for the organization's content.

Tip: Visit DEV's Organization Info page to learn more about organizations.

Create content

Content on DEV is written in Markdown with front matter and various liquid tags for common tasks. Check out the editor guide for a full rundown.

Content that you post on DEV ends up in user feeds, helping your content be seen. Users can heart, unicorn, and bookmark posts. These reactions boost the post's signal and makes it more likely to appear in users feeds.

If your post is really popular or spurs a lot of comments, it might be
included in roundup-style posts shared by the DEV team, like this one:

The 7 Most Popular DEV Posts from the Past Week

Jess Lee for The DEV Team ・ Sep 23 '19

#top7

These roundups are also emailed to users in a weekly newsletter.

Twitter

Posts are sometimes tweeted out to the large and loyal @ThePracticalDev twitter following, which has 165k followers as of September 2019. This can create a lot of engagement and help developers discover your twitter handle. ✨

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

Tip: Make sure you set your twitter handle in your DEV profile.

There are other twitter handles that tweet out posts from specific tags on DEV, like @the_ruby_dev does for #ruby.

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

Analytics

Your DEV dashboard will tell you how well your content is performing. It has one tab for your personal account and one for each of your organizations.

Here's an example. I can see my total number of post reactions and views, shown here for my DeveloperMode organization.

I can also see my stats at the individual post level.

Cross-posting

DEV welcomes cross-posted content and lets you specify a post's canonical_url in the post front matter. That way Google will send visitors directly to your site when the post appears in their search results and the post will accrue to your site's SEO.

This is a very attractive option for organizations who are also investing a lot in their own blogs.

If your blog doesn't have a commenting system or doesn't get many comments, cross-posting to DEV is likely to get you more conversations and feedback than you would otherwise. Make sure to keep an eye out for replies after you post and actively reply to the thread.

Ask and answer questions

Just like your team might monitor StackOverflow or Twitter for questions about your technology, you can also do that on DEV.

The tags and search features will help you find posts about the topics you are interested in and could help out on.

You can ask questions too, which is great for getting opinions and feedback. Content on DEV doesn't have to be long to get good engagement. I recommend making the question succinct and using it as the post's title. Add any additional details in the body and publish.

Sponsor

If you'd like to kick your DEV partcipation up a notch, the team behind DEV does offer sponsorships. Check out the Sponsorship Information page to learn more.

The DEV team does a great job of highlighting their sponsors around the platform. Here's an example:

Introducing our September 2019 sponsors

Ben Halpern for The DEV Team ・ Sep 3 '19

#meta

The #devrel tag

Last but not least, developer relations teams should be aware of the #devrel tag right here on DEV. This is a great place to post content and talk shop about developer relations.

If you have any questions, send me a message or drop them in below. Thanks for reading! 🙏

What conferences are you most excited about this fall?

Josh Dzielak 🔆 — Fri, 26 Jul 2019 15:14:29 +0000

I'm currently planning my calendar and I'd love to get some suggestions from the community. If you're running an event and looking to catch the eye of some potential attendees, feel free to share it here too.

I'm excited about JAMstack Conf San Francisco on October 16-18. I just went to the London edition and loved it ❤️ Amazing speakers, several live product announcements from the likes of Netlify and Stackbit. Overall there was a really friendly and inclusive environment, and for me a lot of developer advocates, and evangelists, and founders of dev companies to connect with. The SF edition will be even bigger, with an additional day of conference in addition to a workshop day.

Photo: Sarah Drasner speaking at JAMstack Conf London 2019

Props for props: how I made a royally unusual talk for JAMstack Conf London

Josh Dzielak 🔆 — Tue, 23 Jul 2019 14:11:38 +0000

There were 4 lightning talks at the reception of this year's JAMstack Conf London. This is the story of how I found myself giving one of them wearing gold sunglasses with an attached crown, and directing the slides with a sceptre.

It all began when the call for the talks said they'd take place in a pub in the evening. So, I thought I'd propose something fun; technical but not too hard for the audience to follow, like a story. This is the proposal I sent over:

"Once upon a time there was a widowed king named King Markdown. Old King Markdown and his subjects preferred their content to be static, linear and mostly text. One day the king met Princess JavaScript of the Most Serene Kingdom of XML. The Princess and her people preferred their content to be colorful, dynamic, and interactive. King Markdown and Lady JavaScript fell deeply in love despite their differences. But how could the content creators of their respective kingdoms ever build JAMstack sites together? For this, a hero would be needed. More than a hero—a Prince."

You can imagine my surprise when I received this email from conference MC Phil Hawksworth:

LOL. Really? They took it seriously. Cool! Ok so...

This is great
I actually have to write this talk now
These are the conference day speakers 😮
I have 11 days

If you'd like to see how the talk turned out, check out the slides or view the code.

Keep reading to see how I designed and built the talk in the days hence, along with some lessons learned about putting together talks on short notice as a highly fallible human being.

The 4 P's

I have a framework for writing and delivering highly-organized and well-rehearsed talks without any stress. It's called The 4 P's.

Panic
Procrastinate
Perspire
Perform

If I just follow the 4 P's, everything will be fine.

🤮🤮🤮🤮

Panic

If panic sounds like a bad thing, that's because it is. But panic is also one place creative ideas come from. Once I start to panic about giving a talk, my brain is forced to come up with crazy ways to make it happen, without caring (yet) if they will actually work.

Often, that creative energy takes me to interesting places, both mentally and physically. For instance, there is a costume store called Circus in between my yoga studio and my office, which I walked by the day after I got Phil's email. As soon as I walked in, lo and behold I saw these matching sunglasses and sceptre.

YES. YES! I'll dress up like a king for the talk. I WILL BE KING MARKDOWN.

I had zero content at this point yet possessed an unshakeable confidence that the talk would require me to spend 30€ at a place called Circus. So I did.

Back at my office, I didn't start writing the talk so much as I went panic-shopping again. I bought a Logitech Spotlight on Amazon for 90€ because I had seen swyx tweet about it and it looked cool. Justifiable procrastination, amirite?

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

If the audience hates the talk, at least I can distract them with this fancy pointer, like they're cats!

The Logitech Spotlight is pretty cool though. It lets you highlight and magnify parts of the presentation just by pointing at the screen and dragging around a circle. It has a built-in accelerometer and requires no external sensor. The Spotlight also has next and previous buttons that can be configured to send custom keystrokes when you double-click them.

I still had no plan and no content, but I had stuff.

Procrastinate

I did nothing for a week except get a haircut.

Perspire

In the 55-hour period from July 7 @ 12pm to July 9 @ 7pm I spent about 30 hours building and rehearsing the talk.

But why did it take that long to build a 10-minute lightning talk?

Yes, why indeed?

MDX Deck

Since I was giving a talk about MDX, I knew I couldn't just build my slides in Keynote or Google Slides like some sort of traveling hypocrite. I had to build them in MDX. That single decision opted me into building an entire single-purpose React application, including a half-dozen new React components and all the custom CSS to go along with them.

Thankfully, there's this great tool that exists called MDX Deck. MDX Deck lets you write slides in markdown and embed React components using JSX syntax (this is what MDX is). I'd just used it to write a talk for JAMstack Paris. It has a presentation mode with support for speaker notes too.

I highly recommend MDX Deck BUT remember you are still coding your slides. There is no drag-and-drop positioning or text-resizing. No flashy transitions. There are some themes and layouts out-of-the-box, but you need to build on top of that with React, styled-components, and all that implies.

$ npm ls --parseable | wc -l
993

This talk brought to you by 993 NPM packages!

These are some of the components I extended or created:

Horizontal: a layout that takes a customizeable width
Appear: to make children appear incrementally without taking up space before they're visible and making the first child visible on initial render
Character: the base component for the king and the princess that renders an image and wires up hover and click handlers
Code: to show code with syntax highlighting
Provider and Footer: to put a footer with twitter handles and the slide number at the bottom of every slide

Why the footer? It's important to have your twitter handle and the conference twitter handle or hashtag showing at all times if you want to make it easy for folks to tweet your talk.

On GitHub you can check out the code for all these components.

Creative direction

The week of procrastination wasn't entirely unproductive, it turns out. A background process running in my brain stitched together a rough idea of how the talk would work.

The Story

The tension in the fairy tale's plot would be a dispute between the King and the Princess around what kind of content the kingdom should produce - text-heavy or interactive.
The kingdom's content team would be called The Royal Academy of Content and the engineers on that team would save the day.
A neighboring sovereignty called the JAMstack Kingdom would hold the secret to combining Markdown and JavaScript components 😉

The Technology

King Markdown and Princess JavaScript will be React components.
When hovered over, some animation will happen.
When clicked on, the code for its React component will appear.

The Props

The Logitech Spotlight will be fastened to the base of the Royal Sceptre and hidden so the sceptre itself appears to be driving the presentation.
The Spotlight will trigger the hover and click events on the characters.
The Spotlight will magnify sections of the code as I explain them.
The Spotlight will change the props of a React component on the fly, literally "props for changing props".

This is what the screen looked like with the Royal Sceptre moving the highlight bubble away from King Markdown and toward the code that produced him.

This effect worked to focus the audience's attention, even in a noisy pub.

Live coding

For whatever reason, the challenge of telling a fairy tale with bespoke React components AND animating it with the world's most expensive clicker didn't feel like enough for a 10-minute talk at a bar.

Surely there had to be some live coding too.

The live coding ended up on Slide 16. The rendered HTML output and code of an instance of Princess JavaScript is shown side-by-side. Thanks to react-live, changing the code in the editor causes the component to re-render instantly.

I didn't have time to wire up the Royal Sceptre to type actual characters (it is possible!) so I just used my laptop keyboard to change the values instead.

Live drawing?

At one point I was rehearsing with the Royal Sceptre and I thought "wouldn't it be cool if I could draw on the slides just by pointing at them?"

I had recently come across an elegant implementation of in-browser drawing on the DEV community's offline page and read Ali Spittel's post about how she built it. Thanks Ali!

How to Create the Drawing Interaction on DEV's Offline Page

Ali Spittel ・ Jul 3 '19

#javascript #art #showdev

I borrowed the code from her Codepen, shoehorned it into a React component, made a few tweaks so that it'd work with the Spotlight pointer*, and boom, it worked!

I made the whole surface area of the final slide drawable by using this React component as the slide's MDX layout:

<Drawable color="#ce4999" width={20}>

# Thank you!

<div style={{ fontSize: "24px" }}>
  Click and hold to draw on the page.
</div>

</Drawable>

At the end of the talk, I pointed the ~~Logitech Spotlight~~ Royal Sceptre at the screen and underlined the words "Thank you".

*In the published slides, you can click the mouse and hold to draw. The Spotlight cannot do that. For the real presentation, I modified the code to draw simply on hover, which can be done by waving the Spotlight around with the top button held down.

Perform

I'd never tested any of this before a real crowd before. I had no idea where the screen would actually be in the bar and if it would even be possible to point at it without turning my back to the crowd. But this is the Perform phase, with no room for Panic.

Phil was very kind and let me do some tests when I arrived at the bar. The screen was behind me but not too far. The Royal Sceptre was able to move the highlighter on it. This was good news.

Then it was go time. I put my laptop down on the bar, plugged in an HDMI cable that was too short, and spoke into the microphone at full volume, making liberal use of the Royal Sceptre. The crowd got into it and we had a lot of fun together.

On twitter, people said they enjoyed the talk. Yay!

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

And another one here:

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

In the end, pushing through the 4 P's and spending the time to build the talk was definitely worth it. I learned at lot about MDX and MDX deck, and it led to many fun conversations with folks who were curious about how it all worked. That gave me the motivation to write about it here.

😅😅😅😅

Conclusion

Is there a conclusion? I hope so.

The 4 P's framework is horrible, please don't write talks that way.

The Logitech Spotlight is very cool and I've only scraped the surface of how it can make very interactive presentations when combined with React and MDX.

Phil and the whole JAMstack Conf crew threw an amazing conference. They're good people. I thank them for selecting my talk and not thinking it was a fake submission.

There's no video but you can see the slides and look at the code to learn about MDX and see how everything in the talk was built.

If you have a question about MDX, MDX Deck, or (not using) the 4 P's, please ask.

Thank you for reading!

MDX, authors and richer JAMstack content

Josh Dzielak 🔆 — Fri, 31 May 2019 17:25:39 +0000

Thanks to the growth of the JAMstack, developers are building performant and secure websites as quickly as ever. Content creators are benefitting from this renaissance too, but at the same time many authors are reaching the limitations of markdown as an authoring tool.

The good news is there’s now a better way: a new format called MDX that empowers content creators to embed dynamic components inside of their markdown.

At the 3rd edition of the JAMstack Paris meetup, I spoke about how developers can empower their creators with MDX. A big thanks to Nicolas Goutay and Matthieu Auger from Theodo for organizing the meetup and to Algolia for hosting us.

MDX is a relatively new file format that just hit v1 in April.

MDX makes JSX components usable in markdown. This allows developers to create rich, interactive components—think forms, polls, charts, layouts and more—which authors can embed elegantly inside of their content.

Here's what an .mdx file looks like, using the example of embedding a question & answer poll inline with normal markdown content:

# Hello, *world*!

This is just markdown here. The JSX is below.

<Poll>
  <Question>What is your favorite language?</Question>
  <Answer>English</Answer>
  <Answer>French</Answer>
  <Answer>JavaScript</Answer>
</Poll>

Markdown continues down here.

JSX syntax is tag-based like HTML, but the abstractions are higher-level, and developers can choose what JSX components to make available to authors.

Developers can (and should) design components in a way that makes them easier for even non-technical authors to use.

MDX holds a lot of early promise for making the JAMstack more authorable, a stated goal of the MDX creator:

"What I mean by authorable is that it's a format that can be naturally written in by all members of a cross-functional team after some learning - from engineering to marketing." — MDX author John Otander

The video of the talk is forthcoming, but for now you can see the talk slides as well as the talk source code, which itself is written in MDX using an excellent slide-making open source project called mdx-deck.

4 lesser known ways to use Ruby’s Enumerable module

Josh Dzielak 🔆 — Wed, 22 May 2019 13:59:53 +0000

A big reason I love Ruby is how much work I can get done in just a few characters or lines of code, and ensuring that code is still easy to read for my peers. One area where this is most apparent is in dealing with arrays and hashes, also known as enumerables in the Ruby world.

Any object that includes Ruby’s powerful Enumerable module can be iterated over, traversed, manipulated, sliced and diced in various ways. This module’s flexibility leads to surprisingly terse code for complex tasks.

When Ruby 2.6 arrived in December 2018, it came with some new methods for Enumerable as well as other improvements to list and sequence handling. In this post, I’ll show you a few capabilities recently added to Ruby’s Enumerable as well as a few old favorites.

Endless ranges

Ranges are a great Ruby feature that allows you to quickly create iterable ranges from numbers or letters, such as 1..10 or ('A'..'Z'). Before Ruby 2.6, the double-dot range syntax required a start and a finish. Now, there’s an intuitive syntax to create these endless ranges—simply omit a final character after the double dots: 1...

Why are endless ranges useful? One obvious use case is as a clean way to generate an ever-growing list of integers:

(1..).each do |i|
  puts i
end
# 1
# 2
# 3
# ...

Another unique way to use endless ranges is to use them in concert with other methods chained onto enumerable. In these cases, the range isn’t exactly endless but just ends when the conditions of the chained methods are satisfied. Let’s look at an example:

p (1..).step(5).take(100)
# [1, 6, 11, 16, 21, 26, 31, 36, 41, 46, …. 491, 496]

What’s happening here? The step(5) method takes each fifth number from the range, which remains infinite. The take method takes the first 100 elements of that sequence, which now becomes finite. Using an endless range to begin the expression ensures that the latter part will work for any set of inputs. We could change the 5 or 100 to larger numbers and still get the expected result.

Tip: Ranges work with letters, too:

p ('A'..'Z').step(2)
# ["A", "C", "E", "G", "I", "K", "M", "O", "Q", "S", "U", "W", "Y"]

The `lazy` keyword

This one isn’t new to Ruby 2.6, but it is powerful and underused. Enumerables support a form of lazy iteration that helps you avoid reading entire files or sets of database records into memory when you might not need to. For example, when you only need to find the first 10 lines in a file that contain the word “jane”.

File.open("names.txt") do |f|
  f.each_line.lazy.select { |line| 
    line.match(/jane/i) 
  }.first(10)
end

Although it’s only one extra method, the addition of lazy after each_line changes what happens under the hood. The entire file isn’t read into memory, as is what would happen without the lazy keyword. With lazy and first(10) at the end of the expression, the file is read line by line, but the reading stops as soon as 10 occurrences are found.

Range stepping

The step method on a range can help you produce a subrange of every 2nd, 3rd, or nth element. Ruby 2.6 brings a bit more power and a new, shorter syntax for stepping.

First off, a new alias for step is available - %:

p ((1..10) % 2)
# [1, 3, 5, 7, 9]

Next, there are now first and last methods that can be called on steps of ranges, which is of type ArithmethicSequence.

p ((1..10) % 2).last
# 9

each_cons

When you need to iterate an array of multiple overlapping elements at a time, each_cons comes in handy. This method produces sub-arrays from consecutive elements similar to slice. However, the first element of the next array is the second element of the previous. This is easiest to see with an example.

p (1..10).each_cons(2)
# [[1, 2], [2, 3], [3, 4], [4, 5], [5, 6], [6, 7], [7, 8], [8, 9], [9, 10]]

each_cons takes an integer argument for how large each array should be.

Because strings are just arrays of characters, each_cons can be used to do some string processing that might otherwise be tedious. Here’s a fun example to make your strings look extra spooky:

str = "arrays and collections are scary"
p str.chars.each_cons(2).map(&:join).join
# "arrrraayyss  aanndd  ccoolllleeccttiioonnss  aarree  ssccaarry"

Another, perhaps more useful way to use each_cons is to keep the previous and next element in context while iterating over a collection.

primes = [2, 3, 5, 7, 11, 13]
primes.each_cons(3).each { |previous, current, next_| 
  p "#{current} is the prime number between #{previous} and #{next_}"
}
# "3 is the prime number between 2 and 5"
# "5 is the prime number between 3 and 7"
# "7 is the prime number between 5 and 11"
# "11 is the prime number between 7 and 13"

You can see another handy Ruby feature happening here: argument destructuring. One array is being passed to the function argument of the each function, but we can provide three parameters: previous, current, and next_ to have Ruby put the 0th, 1st, and 2nd array elements into those variables automatically.

Conclusion

We’ve just scratched the surface of what’s possible with Ruby Enumerables. Hopefully you’ve learned a few tips to tighten up your current or next codebase. Combining endless ranges, stepping, and the lazy keyword can make an entire family of loop processing use cases much easier.

If you’re interested in learning more about how to level up your Ruby code, I highly recommend the Code[ish] Podcast with Aaron Patterson and this episode about Ruby Regexes and How open source developers will make your company stronger.

Thanks for reading!

World Celebrates International Developer Relations Day

Josh Dzielak 🔆 — Mon, 01 Apr 2019 12:57:55 +0000

San Francisco, CA, April. 1, 2019 — Today the world recognizes developer advocates, evangelists and everybody else on the "DevRel" team no matter what crazy title they have.

What is developer relations? The most widely recognized definition comes from the movie Gladiator (2000):

"There was a dream that was DevRel. You could only whisper it. Anything more than a whisper and it would vanish, it was so fragile."

Closing keynote @ Web Summit 2018

Over 3 billion developers have gathered at meetups, conferences and hackathons around the world to cheer on their favorite advocates, and then to ask them support questions.

Several major airlines have partnered to give DevRels free first-class upgrades today as they fly to and from their speaking engagements, homes and offices. You didn't think they'd get the day off, did you?

Earlier today, several vice presidents of innovative developer-facing companies issued a joint statement:

"Today, we're just going to assume the business value of DevRel."

This elicited an enormously positive response from developer relations practitioners worldwide, who instantly closed files like ATTENDEES_COUNT.xls and CONFERENCE_QUALIFIED_LEADS.csv, then shut their laptops and took the elevator down to the lobby bar to celebrate.

Several developer advocates were contacted for this story but curiously all of them responded with the same message: Out Of Office: Traveling.

One advocate did reply a few minutes later and apologized, admitting that she was not actually traveling this week but just needed to go one consecutive 24-hour period this year without talking to anyone.

Teammates from marketing, sales, engineering, business development, product, customer success, human resources and operations came together to celebrate their company's DevRels today, whom they work with on a regular basis. This turned out to be an effective team-building activity as most of those people had never met before.

How can you help celebrate International Developer Relations Day? It's easy.

If you're on the product or engineering team, just this once you can assume that the feedback gathered by your DevRels from the community is, in fact, valid feedback.

If you're on the marketing team, consider taking 90 minutes next week to explain how the navigation inside of Google Analytics works.

If you're in sales, it's easy, just batch up your introduction requests instead of making them one at a time, and under no circumstances ever send a whitepaper to a developer.

If you're a designer or developer that uses the service that your friendly neighborhood DevRel works for, consider holding off on that request for 400% more free quota until next quarter so you don't skew the metrics that their bonus depends on. Maybe also pay their company money someday.

If you are a conference lanyard, please stop twisting around and facing the wrong way.

If you follow a DevRel on twitter, please do not reply to their tweets with "Hot Take" or "Unpopular Opinion". Avoid doing that today and also for the rest of your life, which will be longer.

If you're a manager of a DevRel individual or team, please add an emoji to the calendar invite for your 1:1 meetings, preferably 🤗 or 🙏.

How should you celebrate International Developer Relations Day if you yourself are a DevRel?

Developer Advocate Jessica West recommends that you "Go purchase mini bottles of wine and visit a high rise to pretend like you're on a plane".

Director of Developer Relations Justin Johnson encourages advocates to "Take that money you were going to spend on another .dev domain and buy a plate of tacos instead."

The team at DeveloperMode hopes you'll take today to think about what you need in order to be happy and successful.

Sleep. A lot. Take breaks. Tweet or don't tweet. Sprawl when you're in the airport lounge—that's what those jumbo 1-person couches are for. Don't burn out - burn in. Be proud, but stay humble. Don't drop the mic after your talk no matter how loud the audience is clapping. Microphones are expensive and you won't get invited back next year if you break one.

Happy International Developer Relations Day. You've earned it.

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

How to use the new github.dev personal website generator

Josh Dzielak 🔆 — Mon, 25 Feb 2019 15:18:13 +0000

github.dev is a new community project by GitHub that lives on the .dev TLD. With it, you can fork, customize and deploy a personal site that shows your GitHub bio and contributions, powered by the GitHub API, GitHub Pages, and Jekyll.

Here's my page: dzello.github.io.

Personally, I like this project because it gives developers an alternative way to showcase their coding talents and interests, beyond just their GitHub profile page, which some developers in the community have raised good questions about.

If you already know how to fork a repo and use the command line, I can show you how to get your own github.dev instance up and running in about 10 minutes.

Get started

Point a browser window to the github/personal-website repository.

Click the Fork button to make a copy of the repository in your account
Go to the Settings tab and rename the repository to {username}.github.io, substituting {username} for your GitHub username

Repositories named {username}.github.io do something really unique on GitHub. Their contents (specifically the _site folder) will automatically be deployed to a GitHub Pages URL and become available as a browsable website at this address:

https://{username}.github.io/

This is unfortunately not on the new github.dev domain itself, but I do hope the project's name implies a plan for that 🤓.

Before the site appears, however, you need to push at least one commit to the repo after renaming it. We'll do that in the following steps.

Run locally

As a prerequisite, install Ruby if you don't have it already.

First, clone your new repository.

git clone git@github.com:{username}/{username}.github.io.git

Next, cd into the repository and install Jekyll and dependencies.

cd {username}.github.io
gem install jekyll bundler
bundle install

Now you're ready to start up the site.

bundle exec jekyll serve

Browse to http://localhost:4000 and you should see a page with your name, profile photo and public repositories. This data is already present thanks to the github-metadata Jekyll plugin and the GitHub pages gem.

Customization

No further customization is required (feel free to skip down to #deployment), but do I recommend at least changing your interests so that your page accurately reflects who you are.

Your interests

By default, github.dev assumes you are interested in CSS, Web Design, and Sass. But what if you prefer PostCSS or are not actually a devsigner? Don't worry, it's easy to change.

Open up _config.yml with your favorite text editor and find the topics section. Make changes to the YAML to add, update and remove topics. Here's how you would add the awesome topic for example:

topics:
  - name: awesome
    web_url: https://github.com/topics/awesome
    image_url: https://raw.githubusercontent.com/github/explore/c304601f028774885ef27f72e6fe2d331729d8bc/topics/awesome/awesome.png

Visit the GitHub topics page to see what other interests you can add.

After you make changes to _config.yml, you will need to stop Jekyll and restart it before they appear. Changes to other files, however, should just require a page refresh.

Show popular repos first (optional)

By default, repositories are sorted alphabetically. If instead you want your most-starred repos to be shown instead, you can make a change to the _includes/projects.html file.

<div class="d-sm-flex flex-wrap gutter-condensed mb-4">
  {% assign sorted_repositories = site.github.public_repositories | sort: 'watchers_count' | reverse %}
  {% for repository in sorted_repositories limit:6 %}
    <div class="col-sm-6 col-md-12 col-lg-6 col-xl-4 mb-3">
      {% include repo-card.html %}
    </div>
  {% endfor %}
</div>

The important part is the sort: 'watchers_count' and reverse. There are other fields you can display or sort by too, see the documentation for the github-metadata jekyll plugin. You can also limit the total number of repositories shown, which I am doing above with limit: 6.

🔦 Dark mode (optional)

In _config.yml, you can set style: dark. This will make your visitors' faces glow less while they are reading your site at night.

The customization section of the README contains several more ways to really make your site your own. You can even add a blog, too.

Deployment

Each time you push new commits to GitHub, your site will be built and deployed to https://{username.github.io}/. At least one git push is required before the site is deployed for the first time.

Assuming you made some changes to your interests in the _config.yml file, here's what you should do.

Add and commit your changes:

git add _config.yml
git commit -m 'Updated my interests'

Then push them up to GitHub:

git push

Wait a few minutes and your site should be live at https://{username}.github.io/. 🎉

You can confirm this in the environment tab on the GitHub repo:

Troubleshooting: if for some reason the site doesn't load after a few minutes, try the URL https://{username}.github.io/index.html instead. If that works, there may have been a caching issue, and you'll just need to wait a bit before you can access the site without the index.html.

Congratulations!

Are you excited about your new site? ✨ Drop in a comment below and let's see it! Tell us about any customizations that you made that others might want to try too.

That's it for the tutorial. If you want to see more sites and community projects making their home on the new .dev domain, check out awesome-dot-dev ⭐.