Simplify Your Docs Maintenance Workflow with Reusable Content!

Edit once, update everywhere. Reusable Content blocks help you minimize manual errors and ensure that changes to your developer hub occur in all the places they’re needed. 😉

How Reusable Content Works

Reusable Content, as the name implies, allows ReadMe Admins to create blocks of Markdown content that can be used repeatedly across multiple pages in their projects’ docs. When anyone in your project with Admin access edits and updates a Reusable Content block, it automatically updates across every instance where it’s used—a huge time savings benefit!

Reusable Content acts as a block, and lives in the editor’s slash menu. Creating a Reusable Content block isn’t just for text—it supports all Markdown!—which means you can have Reusable Content blocks that include images, code snippets, callouts, and more!

Benefits of Using Reusable Content Blocks

1️⃣ More efficient documentation creation - for our ReadMe Admins who are responsible for producing and managing extensive API documentation, the ability to make changes across multiple pages in your docs by updating a Reusable Content block (vs. having to hunt for each instance and manually update it) significantly streamlines the docs editing and maintenance workflow!

2️⃣ Better accuracy and fewer mistakes - Fewer manual edits, and more automated changes, means less room for error! Whether it’s including version specific content, adding relevant callouts for specific plan types, or ensuring that all related pages link back to one another, Reusable Content blocks allow your team to scale documentation production and ensure greater quality assurance across the board.

3️⃣ More clarity across your documentation = a better UX for developers visiting your hub - Reusable Content blocks allow Project Admins to streamline and unify how they communicate concepts that are repeated throughout your developer hub. Developers rely on your documentation to understand how to integrate and successfully use your API or product, and when that documentation is clear and consistent, it helps developers have a better experience in your hub and with using your API/product overall!

📘

Reusable Content is available on ReadMe Business and Enterprise plans!

If you’re on our Business or Enterprise plans, you’ll be able to create Reusable Content blocks from the Editor slash menu (or by using the < syntax). Enterprise Groups will also have access to the Reusable Content page in their Enterprise Group dashboard. If you’re on our Free, Startup, or Open Source plans, you’ll need to upgrade your plan in order to access this feature. You can do that in the Upgrade Plan page in your project dashboard!

Using Reusable Content Across Your Project

Business plan project dashboards and Enterprise child projects have a Reusable Content page in the Documentation section of their project dashboards. This page provides a centralized place to see and manage all Reusable Content blocks used across a project. Within this page Admins can create new Reusable Content blocks, edit existing ones, and delete blocks (only if they’re not being used in any pages).

Creating a New Reusable Content Block on a Guides or API Reference Page

There are two ways to create a new Reusable Content block in a Guides or API Reference page in your project dashboard.

Option 1: Highlight an existing block and “Make [it] Reusable”

If you have an existing Markdown block that you’d like to make reusable, use the Block Actions menu to select the text and choose the Make Reusable option. From there, you’ll be able to make additional edits in the Reusable Content editing window before saving the block.

Option 2: Create a new Reusable Content block from the editor’s Slash menu

Similar to how you’d create any Markdown block, type / to bring up the Slash menu and navigate over to the Reusable Content section. There are two options: Create New and Reuse Content.

Whether you highlight an existing block to make it reusable or select “Create New” from the Reusable Content section of the Slash menu, this Reusable Content window will appear. This is where you’ll name the reusable content block (this is only used internally), can create and make edits to the block, and save it to make it reusable.

🚧

You cannot edit the name of a Reusable Content block once it’s been created

Once you name your Reusable Content block, you cannot change or edit the name. You can only edit the body content of the block.

Adding a Reusable Content Block to a Page

Just as there are two ways to create a new Reusable Content block, there are also two ways to insert an existing Reusable Content block into a Guides or API Reference page.

Similar to how you insert a variable or glossary term, typing “<” in a page will bring up a menu of your project’s Reusable Content blocks, in addition to your glossary terms and variables. Select the Reusable Content block you want to use from the list to insert it onto the page.

You can also insert a Reusable Content block from the editor’s Slash menu. Select the “Reuse Content” option from the menu to see a list of all available Reusable Content blocks. Scroll through the options, select the one you want to use, and it’ll be inserted into the page!

Identifying a Reusable Content Block in Use

Reusable Content blocks have a green border and are labeled as REUSABLE in the editor.

Features:

1. The left label identifies the block as Reusable and lists the name of the block
2. If you click the left dropdown, you’ll have the option to edit or detach the block
3. The right label notes how many pages this particular block is used across
4. If you click the right dropdown, it reveals the specific pages where the Reusable Content block is in use

Editing a Reusable Content Block

When you click the left label dropdown in an Reusable Content block and select Edit, the editing window will appear. If you are on a Business plan (or creating a block for a single Enterprise child project), you can edit the Reusable Content block and click Update which will update the Reusable Content block info across all instances where it’s being used. If you are on an Enterprise project, head to this page in our Enterprise Guides to learn more about the process.

In this editing window there’s also an option to Delete which deletes the block entirely. In order to delete a Reusable Content block you must first remove—either by deleting or detaching—all instances of it across your project.

Detaching a Reusable Content Block

If you want to remove the instance of a Reusable Content block or want to make an edit to a block on one page that you don’t want to be reflected across all instances, consider detaching the block.

You can do this via the left dropdown menu at the top of the Reusable Content block. Select Detach and the block will immediately revert to its original Markdown state.

⏭️

Looking for More Information About Reusable Content for Your Enterprise Group?

We have a separate page for that! If you’re an Enterprise customer looking to learn more about managing Reusable Content for your Enterprise Group, head to this page!

Reusable Content FAQs

How do you find the Reusable Content blocks that already exist for your project?

There are currently two ways to locate the Reusable Content blocks that have been created for your Business plan project (or Enterprise child project) – (1) you can locate them via the editor slash menu (Reusable -> Reuse Content -> populates a list of all Reusable Content blocks) or (2) use the < syntax to bring up the menu of all RC blocks (in addition to your project’s glossary terms and variables).

What are some things to keep in mind when using Reusable Content blocks?

• You cannot nest a Reusable Content block within another Reusable Content block
• A Reusable Content block is saved separately from the page in which it’s being used. To update a block, save the change in the Reusable Content editing window, and then save the page you’re working in
• When you initially create and save a Reusable Content block, the block will say “used in 0 pages”. You’ll need to save the page in order for the block count to update to say “used in 1 page”
• If you export a project to .md files, and then re-import that file back into ReadMe, any previously created Reusable Content blocks that were exported will no longer be recognized as Reusable Content blocks in the new project. If the new project is on Business or Enterprise, you will be able to create new Reusable Content blocks

How does versioning work with Reusable Content blocks?

• Each version of your ReadMe project has its own subset of reusable blocks
• You can’t use reusable blocks across versions, unless you manually clone them and add them to a new version. Even still, once you update in one version, they won’t auto-update in other versions
  • E.g., if you create a new version of your project, v2.0, that is forked from v1.0, the new version will include any Reusable Content blocks that were created and used in v1.0. The Reusable Content blocks that are now in v2.0, however, are different—and while still reusable and auto-syncing—do not sync with the Reusable Content blocks in v1.0 (even though the blocks have the same name). The count for how many times a Reusable Content block is used is tied to the version level.

How do Suggested Edits work with Reusable Content blocks?

• You cannot suggest an edit on a Reusable Content block—this applies to both logged-in users and Admins viewing your project from the hub
• Logged-in users can suggest to move a Reusable Content block, remove it from the page’s content, and detach it
• To suggest an edit to the content of a Reusable Content block, the end user will first need to detach the block and then edit that content
• When the above happens, Project Admins will have the option to merge the suggestion from the project dashboard, as is the case with all Suggested Edits

What happens if you upgrade or downgrade your plan?

• Currently, Reusable Content is only available on Business and Enterprise plans
• Reusable Content is also included in ReadMe’s 14-day free trial
• If you downgrade from a plan where you had access to and had previously created Reusable Content blocks, the following will happen:
  • The Reusable Content blocks will still exist in the pages of your project
  • These blocks will be in ‘view only’ mode—you won’t be able to edit them unless you detach them
  • You’ll also lose the “Used In” menu and will not be able to see where the blocks are used across the project
• If you then upgrade back to Business or Enterprise, then:
  • You’ll gain access back to any existing Reusable Content blocks and have the ability to create, update, detach, and/or delete existing and new Reusable Content blocks