Recipes
Step-by-step code walkthroughs for your most popular API use cases
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.
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 is the first step!)
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:
- Highlighted Steps (left sidebar)
- Code (upper right)
- 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 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)
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:
Emoji Selection
Click on the emoji to select any other character from the dropdown
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 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.
Select the Recipe block from the Blocks Menu
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.
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.
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 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!
Updated about 1 year ago