Recipes are a simple way to walk developers through a code sample step by step to help them get started with your APIs faster. They make it easy to highlight what’s possible with your APIs and explain your best use cases. If you have example code hosted in GitHub with lots of detailed comments, Recipes are the best way to bring that content into your ReadMe project!

Each Recipe can support code samples in multiple languages, with each step annotating different lines within your code. Recipes are published in the dedicated Recipes section of your ReadMe Hub once you've made this section publicly visible. They can also be embedded in any Guide page or relevant endpoints in your API Reference for quick access.

The Recipes page

You can create and view Recipes on the /recipes page of your ReadMe project. This includes editing and publishing Recipes in this section, rather than in your admin dashboard.

From your admin dashboard, click Recipes in your sidebar menu to open your /recipes section on the frontend in a new tab. (Over time, more editing in ReadMe will happen directly in your docs in this way — Recipes is the first step!)

Creating a Recipe

Recipes are created in two steps: configuration and appearance settings. We'll walk you through both here.

Each Recipe has three areas to configure:

1. Highlighted Steps (left sidebar)
2. Code (upper right)
3. Response (lower right)

Highlighted Steps

Explain certain lines of the code in steps to break down what's happening. You can add, edit, or rearrange steps at any time.

Code

After selecting the right language, paste the code sample that you want to walk through in this Recipe. As a helpful starting point, you can also select Choose Endpoint to pull in the request code from any of your existing endpoints.

Enter the line numbers that should be highlighted for each step. Each language can have its own highlight instructions.

Response

The successful response to running the code goes in this area. If you clear the default {"success":true} response, this section will disappear.

👍

User data variables work in Recipes!

If you have variables in your documentation, for example passed in via the Personalized Docs Webhook, they'll work in Recipes too!

Once you've configured your Recipe, you can also customize four aspects of a Recipe's appearance:

1. Emoji and Background Color
2. Embed in relevant endpoints
3. Recipe Description
4. Preview

Emoji Selection

Click on the emoji to select any other character from the dropdown

Background Color

This color picker sets the background color for the emoji. You can toggle between RGB, HSL, or HEX. The "Open Recipe" button color is inherited from the Link Color you've set in the Theme Editor in your project settings.

Embed into relevant Endpoints

All the endpoints in your Reference section will be listed in the Appearance section. Select the ones where you want to embed this Recipe. You can also embed a Recipe in the Guides section later.

The Recipe will appear as a clickable card as shown in the preview area of the Appearance step.

🚧

Embeds will not appear in the Reference section until the Recipes section is enabled.

Recipe description

This description will appear on the larger Recipe card in the /recipes section. The smaller card that embeds into Guides and Reference will not contain the Recipes description.

Preview

Publishing a Recipe

A Recipe can be in one of three states: Featured, Published, or Unpublished

Embedding a Recipe

Recipes can be embedded on a Guide page by dragging and dropping the Recipe widget into your content. You can also embed Recipes in the Reference section.

The Recipe block will allow you to choose any Recipe. Once embedded, clicking on the Recipe card in your Guide will quickly open the Recipe as a modal in the same window.

🚧

The Recipe widget will not appear until the Recipes section is enabled.

This is what an embedded recipe looks like:

Enabling your Recipes page

📘

Recipe icon in navigation bar

The Recipes icon is always visible in the nav bar to project admins in order to access the section.

But if it looks more faded than the other icons, the section is not enabled and therefore not visible to your customers. View your docs while logged out (or from an incognito window) to be sure.

Recipes can be enabled by hovering over the "Show Recipes" button directly on your Recipes page.

This will make the Recipes section visible to your users in the navbar and allow them to see all of your published Recipes. Unpublished Recipes will never be visible to your users.

Project admins will always see the Recipes icon in order to access the section, but it will look grayed out if the section is not enabled for customers.

Alternatively, you can toggle Recipes on or off in the editor under Appearance > Site Navigation.

FAQ

Can I remove the Recipe icon in the nav bar?

This section is only visible to project admins. Your customers will not see this section unless you enable it to make it visible to them.

As we transition more editing capabilities to the frontend of your docs hub, we'll continue to make it clearer what project admins see versus what your customers see.

How do I change the color of the blue "Open Recipe" button?

This button color is inherited from the Link Color you've set in the Theme Editor in your project settings. To change it, you will need to change the Link Color for your entire ReadMe hub.

Can I rename the Recipe section like the other sections?

Not yet, but we're working on it!