diff --git a/README.md b/README.md index 1452ea73..36476742 100644 --- a/README.md +++ b/README.md @@ -231,6 +231,15 @@ $ php artisan api:update As an optional parameter, you can use `--location` to tell the update command where your documentation can be found. +## automatically add markdown to the beginning or end of the documentation + +If you wish to automatically add the same content to the docs every time you generate, you can add a `prepend.md` and/or `append.md` file to the source folder, and they will be included either above, or below the generated routes (or both). + +**File locations:** +`public/docs/source/prepend.md` +`public/docs/source/append.md` + + ## Skip single routes If you want to skip a single route from a list of routes that match a given prefix, you can use the `@hideFromAPIDocumentation` tag on the Controller method you do not want to document. diff --git a/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php b/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php index 857be1ca..99e68c9a 100644 --- a/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php +++ b/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php @@ -103,6 +103,8 @@ private function writeMarkdown($parsedRoutes) $outputPath = $this->option('output'); $targetFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'index.md'; $compareFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'.compare.md'; + $prependFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'prepend.md'; + $appendFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'append.md'; $infoText = view('apidoc::partials.info') ->with('outputPath', ltrim($outputPath, 'public/')) @@ -152,12 +154,24 @@ private function writeMarkdown($parsedRoutes) }); } + $prependFileContents = ''; + if (file_exists($prependFile)) { + $prependFileContents = file_get_contents($prependFile); + } + + $appendFileContents = ''; + if (file_exists($appendFile)) { + $appendFileContents = file_get_contents($appendFile); + } + $documentarian = new Documentarian(); $markdown = view('apidoc::documentarian') ->with('writeCompareFile', false) ->with('frontmatter', $frontmatter) ->with('infoText', $infoText) + ->with('prependMd', $prependFileContents) + ->with('appendMd', $appendFileContents) ->with('outputPath', $this->option('output')) ->with('showPostmanCollectionButton', ! $this->option('noPostmanCollection')) ->with('parsedRoutes', $parsedRouteOutput); @@ -174,6 +188,8 @@ private function writeMarkdown($parsedRoutes) ->with('writeCompareFile', true) ->with('frontmatter', $frontmatter) ->with('infoText', $infoText) + ->with('prependMd', $prependFileContents) + ->with('appendMd', $appendFileContents) ->with('outputPath', $this->option('output')) ->with('showPostmanCollectionButton', ! $this->option('noPostmanCollection')) ->with('parsedRoutes', $parsedRouteOutput); diff --git a/src/resources/views/documentarian.blade.php b/src/resources/views/documentarian.blade.php index 9e2a136a..83d7c37d 100644 --- a/src/resources/views/documentarian.blade.php +++ b/src/resources/views/documentarian.blade.php @@ -5,15 +5,19 @@ {!! $infoText !!} +{!! $prependMd !!} + @foreach($parsedRoutes as $group => $routes) @if($group) #{{$group}} @endif @foreach($routes as $parsedRoute) @if($writeCompareFile === true) -{!! $parsedRoute['output']!!} +{!! $parsedRoute['output'] !!} @else {!! isset($parsedRoute['modified_output']) ? $parsedRoute['modified_output'] : $parsedRoute['output']!!} @endif @endforeach @endforeach + +{!! $appendMd !!}