The theming system is still experimental. It won't change significantly, but we're looking for ways to make it simpler and more consistent. We're open to your suggestions!
Scribe v3 comes with support for themes, allowing you to customize how your docs look. Scribe currently only comes with one theme,
default, but you can create a new theme. Let's see how.
A theme consists of:
index.blade.phpfile that takes the API details and renders to HTML. For custom themes, this file has to be in
- any accompanying CSS and JS files. You can place these anywhere in your codebase, as long as you reference them correctly from the theme file (keeping in mind the actual path your docs/ page will be visited from).
When you run
php artisan scribe:generate, Scribe will use the theme template to generate the HTML. For inbuilt themes, it will also copy any CSS and JS files to your app's public directory. For custom themes, you'll have to manage that part yourself.
To create a new theme (let's call this theme
nasty), place the
resources/views/vendor/scribe/themes/nasty/. Next, we change the value of
theme in our config:
Now we write the theme. Writing a theme file can be a lot of work, so we recommend using the default theme as a starting point. Here's a very simple theme file:
Our theme file is a regular Blade/HTML page. We can do whatever we wish in here, and use Blade constructs as normal. Let's see what's going on here:
First, we're using the
$metadata object that's passed to our theme. This object has the following structure:
Next, we reference a stylesheet,
nasty.css, which we've placed in our
public/docs folder, as well as the highlight.js CSS and JS for syntax highlighting.
Then, in the
<body>, we output the
$auth information. Those variables hold basic HTML containing the text for the introduction and authentication sections.
In addition to these variables, the theme file has access to the following variables:
$baseUrl: the base URL to be displayed in the docs
try_it_outsection from your config file
$append: the HTMl from any
.scribe/append.mdfile added by the user
$groupedEndpoints: the endpoints in the API, organized by groups. Each item in this array is an array with the following shape:['name' => 'The group name','description' => 'The description','endpoints' => [// Array of Knuckles\Camel\Output\OutputEndpointData]]
Finally, you'll notice that at the end, we include
"scribe::themes.default.groups". This means our theme just changed the outer page structure, and falls back to the default theme to render the actual endpoints and groups. This is a great way to modify an existing theme. If we wanted to create a totally new theme, then we would replace the include directive with our own custom Blade that would loop over the groups and render endpoints.
Now when you run
php artisan scribe:generate, Laravel will load your custom theme instead of the default.
If you need a starting point or more guidance to create your own theme, you should look at the included theme files.
Knuckles\Scribe\Tools\WritingUtils class contains some helpful utilities that might save you some work; for instance, printing query parameters as a key-value hash.
If you really want to customise all the templates Scribe uses for generating, you can publish the vendor views:
- Create the
resources/views/vendor/scribe/directory in your app
- Copy the contents of
When you do this, your
resources/views/vendor/scribe/ folder should have this structure:
components folder contains some Blade components used in the themes. For instance, you can display a badge using the
partials folder contains the example request templates. If you want these alone, you can run
php artisan vendor:publish --tag=scribe-examples instead.
markdown folder contains the templates for the intermediate Markdown files that will be generated in your
.scribe folder (
auth.md). If you want these alone, you can run
php artisan vendor:publish --tag=scribe-markdown instead.
- In the
intro.blade.php, you have access to: -
$description(the API description),
$introText(the text for the introductory section), and
$baseUrl(the URL to be displayed in the docs).
- In the
auth.blade.phpfile, you have
trueif the API has auth enabled),
$authDescription(generated by Scribe from your
auth.extra_infosection in your config)
themes folder contains the templates for the included themes. If you want these alone, you can run
php artisan vendor:publish --tag=scribe-themes instead.