Recipes

Step-by-step code walkthroughs for your most popular API use cases

Recipes are a simple way to walk developers through a code samples 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 is 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.

click image to enlargeclick image to enlarge

click image to enlarge

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 in the first step!)

Or head there directly by typing `/recipes` in your URL after your custom domain.Or head there directly by typing `/recipes` in your URL after your custom domain.

Or head there directly by typing /recipes in your URL after your custom domain.

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.

choosing a new endpoint will replace any existing code in this areachoosing a new endpoint will replace any existing code in this area

choosing a new endpoint will replace any existing code in this area

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

Highlight multiple lines with any combination of hyphens (4-6) or commas (4-6, 7, 13-14)Highlight multiple lines with any combination of hyphens (4-6) or commas (4-6, 7, 13-14)

Highlight multiple lines with any combination of hyphens (4-6) or commas (4-6, 7, 13-14)

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 use JWT to pass variables into your ReadMe documentation like <<user>> or <<apikey>> they will 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

Select "None" to show the background color only.Select "None" to show the background color only.

Select "None" to show the background color only.

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

Featured

This is the showcased Recipe at the top of the Recipe section. One Recipe must be featured if your Recipes page is public, and it must be in a published state.

Published

Visible to users in the card grid below the featured Recipe

Unpublished

Cannot be seen by customers. New Recipes are unpublished by default.

Use left/right arrows to change order in the gridUse left/right arrows to change order in the grid

Use left/right arrows to change order in the grid

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.

Drag the widget onto the pageDrag the widget onto the page

Drag the widget onto the page

The widget will allow you to choose any Recipe and align it left, right, or center. 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 look like on Align Left:

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.

The toggle is on which means users can view the Recipe section.The toggle is on which means users can view the Recipe section.

The toggle is on which means users can view the Recipe section.

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.

Your users will see the Recipe section in the nav bar once the section is enabled.Your users will see the Recipe section in the nav bar once the section is enabled.

Your users will see the Recipe section in the nav bar once the section is enabled.

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

scroll down in Site Navigation until you see these toggle switchesscroll down in Site Navigation until you see these toggle switches

scroll down in Site Navigation until you see these toggle switches

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!


Did this page help you?