Documentation Structure

🚧

Beta

Bi-directional sync is currently in beta. If you’d like to try it out, please join the waitlist in the admin dashboard, or reach out to [email protected].

Project structure

Each ReadMe project will be equivalent to a GitHub repository. See the diagram below:

File Organization

The bi-directional sync feature offers a format that closely mirrors the well-organized ReadMe project structure. With folders neatly organizing your documentation and markdown files serving as individual pages, it creates a user-friendly experience that will feel instantly familiar to ReadMe users.

Your documentation follows this standardized structure:

📂 project
├── 📁 custom_blocks
├── 📁 custom_pages
├── 📁 docs
│   ├── 📂 category-folder
│   │   ├── 📄 page.md
│   │   └── 📃 _order.yaml
│   └── 📃 _order.yaml
├── 📁 recipes
└── 📁 reference

Each component serves a specific purpose:

• custom_blocks: Stores any custom blocks you’ve created.
• custom_pages: Stores any custom pages you’ve created.
• docs: Contains your main documentation content, organized in categories.
• recipes: Holds step-by-step tutorials and how-to guides.
• reference: Contains API reference documentation.
• _order.yaml: Manages the navigation structure for each section.

This organization mirrors your ReadMe project structure, making it easy to maintain consistency between your Git repository and ReadMe documentation.

File Format

Documentation pages use Markdown with front matter metadata:

---
title: List all owls
api:
  file: hoot.json
  operationId: get_owls
hidden: false
metadata:
  title: My SEO Title
  description: A brief description for SEO
  keywords:
    - keyword1
    - keyword2
---

# Main Content

Your documentation content goes here...

Guides Structure

Page order and navigation are controlled by _order.yaml files:

- welcome-page
- getting-started
- advanced-topics
  - feature-one
  - feature-two

API Reference Navigation Structure

Code Example

- reference:
  - Owl Sanctuary API:
    - owls:
      - postowls
      - index
      - getsightings
      - getowlsid
      - getowls
    - habitats:
      - index
      - gethabitats

Image Example

This is after uploading a sample OAS file, hoot.json. The above matches the following sidebar: