A well-organized documentation site helps your users find exactly what they need without frustration. By reordering your documentation sections, you can create a logical, easy-to-follow navigation flow that guides readers from basic concepts to advanced tutorials.

Because documentation structures often vary between different releases, section ordering is managed on a per-version basis.

flowchart TD
    Doc["Documentation Project"] --> V1["Version 1.0 (Latest)"]
    
    subgraph Current Order
    V1 --> S1["1. Introduction"]
    V1 --> S2["2. Quickstart"]
    V1 --> S3["3. API Reference"]
    end
    
    S3 -. "Move up" .-> S2

Reordering sections via the API

You can programmatically adjust the order of your sections using the GitDocAI API. This is especially useful if you are syncing your documentation structure from an external CMS or a local configuration file.

Prerequisites

Before you can reorder sections, you will need:

• Your organization_id and documentation_id.

• The specific version_id you want to modify.

• The IDs of the sections you want to reorder.

Step-by-step guide

1. 1

   Prepare your new order

   Determine the exact sequence you want your sections to appear in. You will need to provide an array of section IDs in your desired top-to-bottom order.

2. 2

   Send the reorder request

   Make a POST request to the reorder endpoint, passing your organization, documentation, and version IDs in the URL path.

   curl -X POST "https://api.gitdocai.com/v1/documentation/{org_id}/{doc_id}/version/{version_id}/section/reorder" 
     -H "Authorization: Bearer YOUR_API_TOKEN" 
     -H "Content-Type: application/json" 
     -d '{
       "section_ids": [
         "8e105a32-33f6-45c1-9a39-80b795fa551b",
         "4a79f9c9-4a13-431a-b894-ab740032f9bd",
         "a5bee53f-a233-4b71-9c7f-48c473ffd9be"
       ]
     }'

3. 3

   Verify the changes

   Refresh your documentation frontend or fetch the sections again via the API to confirm that the navigation menu reflects your new order.

Managing your sections

Reordering is just one part of keeping your documentation structure clean. You can fully manage your sections using the following endpoints: