LaravelにMarkdownのドキュメントサイトを作成できるパッケージ LaRecipe

インストール

LaRecipeはLaravelにComposerで追加します。
Laravelがインストールされていない場合はインストールしましょう。

1
$ composer create-project --prefer-dist laravel/laravel LaRecipe

下記コマンドで、LaRecipeパッケージをインストール。

1
$ composer require binarytorch/larecipe

インストールが完了するとlarecipeのartisanコマンドが追加されるので下記を実行します。

1
$ php artisan larecipe:install

これでインストール完了です。
ビルトインサーバーを使用している場合はhttp://localhost:8000/docsにアクセスして確認してみましょう。
こんな感じに表示されます。

マークダウンファイルの管理

マークダウンファイルはresourcesにdocsディレクトリが新しく作成されているので、この中に作成していきます。
インストールした段階で1.0ディレクトリとその中にサンプルファイルが入っています。
バージョンで切り替える仕組みがあるので、バージョンディレクトリ毎に作成するのがよさそうです。

index.mdが左メニューのファイル、overview.mdは最初に表示されるファイルです。

1
- ## Get Started
2
  - [Overview](/{{route}}/{{version}}/overview)

1
# Overview
2

3
  ---
4

5
  - [First Section](#section-1)
6

7
  <a name="section-1"></a>
8
  ## First Section
9

10
  Write something cool.. 🦊

先頭にこのような書式で追加することで右のページ内メニューに追加されるようです。

1
- [1番目のセクション](#section-1)
2
- [2番目のセクション](#section-2)

Vueコンポーネントも使える

Vueコンポーネントがデフォルトでいくつか用意されているので、これを使えばいい感じに表示してくれそうです。

1
<larecipe-card shadow>
2
    Example card
3
</larecipe-card>
4

5
<larecipe-button radius="full">Example button</larecipe-button>
6
<larecipe-button type="success" radius="full">Success button</larecipe-button>

マークダウンファイルだけど、タグも書くことができるので、自分でコンポーネントを作成することもできそうですね。

その他404ページやナビゲーションなどのファイルは⁨resources/views/vendor/larecipe/partials⁩にあります。

設定ファイルの編集

設定ファイルはconfig/larecipe.phpに生成されているので、このファイルを編集します。
docsではドキュメントのファイルパスや最初に表示されるページを変更できます。

1
'docs'        => [
2
  'route'   => '/docs',
3
  'path'    => '/resources/docs',
4
  'landing' => 'overview',
5
],

バージョンを増やす場合はversionsを編集します。

1
'versions'      => [
2
  'default'   => '1.0',
3
  'published' => [
4
    '1.0'
5
  ]
6
],

たとえば2.0というディレクトリを作成したらpublishedに'1.0','2.0'と追加するだけでメニューで切り替えられるようになります。

その他にも設定できる項目がありますので、詳しくは公式ドキュメントをご確認ください。

LaRecipe