Project starter: Documentation with Reef

Reef is a documentation platform designed for both readers and writers. We at Redocly use it ourselves for the documentation you are reading now. This starter project demonstrates some of the content features and information architecture that you can use in your Revel, Reef, or Realm projects.

Features include:

A home page and subheadings to make the page more navigable with the table of contents feature.
Information and examples of how to reuse (or single-source) content with Markdoc partials.
Folder structure to influence the URL structure.
Sidebar customization and grouping.
Tips and examples for using some of our finest features including: code samples, tabs, and tables.

Get the project and set it up

Use the API reference docs starter project repository to begin. This project is a template repository, so click "Use this template" to get your own copy of the project.

Once you have your own copy of the project in a repository that you own, you can connect it to Reunite, Redocly's hosting platform, immediately.

To connect your repository in Reunite:

Log in to your Reunite account and Create a new project. The project is where you deploy your project from (note that only Redocly hosting is supported; these projects are not licensed to deploy from other platforms).
Connect the Git provider where your repository is hosted.
Wait for the project to build.

Preview locally

Alternatively, clone your copy of the template repository to your computer and run it locally for a quick preview, using the following steps:

Install Redocly CLI.
Run redocly preview in your terminal to see your project.

Tour the project features

This starter project has multiple features; we'll examine each one in turn.

Home page

Add a default page for each folder by creating a file named index.md.

Structure the navigation exactly as you want it by adding entries to sidebars.yaml. Group navigation items, add separators, and make it your own.

Content reuse

Markdoc has support for a feature called "partials" that allows taking a snippet of content and including it within other content. For larger documentation projects that benefit from content reuse, the partials feature is a powerful tool to achieve it.

Visit the partials page in our Markdoc tag library to learn more about the syntax and how the feature works.

Features for authors

Our goal is to make Technical writers' lives easier. This starter project includes examples of the tools you'll use to create compelling content:

Use code samples to present code, with syntax highlighting, copy button and feedback features included by default.
Lay out data in list-style tables; humane to manage, and beautiful to read.
Organize multiple variations of information using tabbed sections.
Create and maintain diagrams-as-code using Mermaid.

Action points

Try these activities to get to know your Redoc project better:

Create an "About" page for your own project, write some content and add it to the sidebar.
Pick a popular page from another docs site, such as your own, and try rebuilding it with the Redocly tools. Include images and code samples if you have them.
Add some links to the navbar at the top (hint: the navbar docs will help).