Guides

Since 0.13.53

Guides are Markdown pages displayed alongside the API reference in Fabric. You can use them to document authentication, pagination, or workflows involving multiple endpoints.

By default, guides appear in the introduction. You can also place them inside endpoint groups. Fabric includes guide contents in search, and each guide has a URL you can link to directly.

Add your first guide

Write the Markdown

Create resources/docs/authentication.md:

---
title: Authentication
order: 1
---

Use an API token from your account settings to access the commerce API.

## Send your token

Include your token in the Authorization header:

```http
GET /api/products HTTP/1.1
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

A guide supports headings, links, lists, and fenced code blocks with syntax highlighting. The frontmatter supplies the page title and sidebar order.

Register the guide

In config/scramble.php, add the file contents under renderers.fabric.guides:

1
'renderers' => [
2
    // Other renderers...
3
    'fabric' => [
4
        'view' => 'scramble::fabric',
5
        'guides' => [
6
            'authentication' => file_get_contents(
7
                resource_path('docs/authentication.md'),
8
            ),
9
        ],
10
    ],
11
],

Each key identifies a guide, and each value is its Markdown source, including frontmatter. Fabric receives the contents, so the file does not need to be publicly accessible.

Open the documentation
Visit /docs/api. Authentication appears below Overview, before the endpoint reference.
You can link to it at /docs/api#guides/authentication. Choose stable, unique guide keys: changing the authentication key also changes that URL.
If you cache Laravel’s configuration, rebuild the cache after adding or editing a guide. The configuration stores the file’s contents:
```
php artisan config:cache
```

Place a guide next to endpoints

To place a guide inside an endpoint group, add group to its frontmatter. The value must match the group’s tag name.

For example, create resources/docs/products.md for a Products group defined with #[Group('Products')]:

---
title: Working with products
order: 1
group: Products
---

Learn how to create a product and organize it into categories.

Add the file to renderers.fabric.guides in config/scramble.php, keeping any existing guides:

1
'guides' => [
2
    'authentication' => file_get_contents(resource_path('docs/authentication.md')),
3
    'products' => file_get_contents(resource_path('docs/products.md')),
4
],

Fabric places Working with products before the endpoints in the Products group:

Working with products guide placed before List products in the Products group, alongside the Categories group.

Match the tag’s name exactly, including capitalization, even if it uses a different summary as its display label. Grouped guides work inside nested groups and sections too. If no matching endpoint group exists, Fabric creates a separate folder for guides with that group name.

Guide frontmatter

Use these optional frontmatter fields to control each page:

Field	Purpose
`title`	The page title and sidebar label. Defaults to the guide’s key when omitted.
`order`	Sort order among guides in the same location, with smaller numbers first. Guides without an order follow those with one.
`group`	The exact tag name where the guide should appear. Omit it to keep the guide in the introduction.

Guide order does not change endpoint order. Grouped guides appear before the endpoints in their group.

Open a guide first

By default, Fabric opens the overview page. To open a guide instead, set renderers.fabric.overview to false in config/scramble.php:

1
'overview' => false,

Fabric opens the first introduction guide, falling back to the first grouped guide or endpoint when there are no introduction guides.

For example, if Authentication is the introduction guide with the lowest order, it becomes the page displayed at /docs/api.