Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aw-studio/docdress
A package to create markdown documentations from GitHub repositories in your Laravel project.
https://github.com/aw-studio/docdress
Last synced: about 2 months ago
JSON representation
A package to create markdown documentations from GitHub repositories in your Laravel project.
- Host: GitHub
- URL: https://github.com/aw-studio/docdress
- Owner: aw-studio
- License: mit
- Created: 2020-08-18T09:46:11.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-03-21T13:26:42.000Z (almost 4 years ago)
- Last Synced: 2024-04-10T05:00:46.728Z (9 months ago)
- Language: Blade
- Homepage:
- Size: 1.34 MB
- Stars: 60
- Watchers: 5
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Docdress
A package to create markdown documentations from GitHub repositories in your
Laravel project. Easy editing for contributors.
The example image shows the [litstack documenation](https://litstack.io/docs).
The GitHub repository can be found under
[litstack/litstack.io](https://github.com/litstack/litstack.io).
## Table Of Contents
- [Introduction](#introduction)
- [Setup](#setup)
- [Add repository to Config](#add-repository-to-config)
- [Clone repository](#clone-repository)
- [Structure](#structure)
- [Readme.md](#readme-me)
- [Table of Contents](#toc)
- [Configuration](#configuration)
- [Versions](#versions)
- [Private repositories](#private-repositories)
- [Webhook](#webhook)
- [Algolia](#algolia)
- [Authorization](#authorization)
- [Alerts](#alerts)
- [Search Component](#search-component)
- [Testing](#testing)
## Introduction
With Docdress you can turn your project/package documentation within minutes
into a web interface with a Laravel-like design.
Docdress offers the following features:
- Laravel-like design
- Documentation for private repositories
- Documentation from subfolders of repositories
- Automatically updated by webhooks
- Any number of repositories in a Laravel project
- Custom themes
- Authentication
## Setup
Install **Docdress** via composer:
```shell
composer require aw-studio/docdress
```
Now publish the required assets and the config:
```shell
php artisan vendor:publish --provider="Docdress\DocdressServiceProvider"
```
You may also publish the `config` or `assets`only like this:
```shell
php artisan vendor:publish --tag="docdress:assets"
php artisan vendor:publish --tag="docdress:config"
```
### Add repository to Config
Add the desired repository to the `docdress` config.
```php
'repos' => [
'my/repo' => [
//
],
],
```
### Clone repository
Once you have configured the repository, you must clone it using
`docdress:clone`:
```shell
php artisan docdress:clone "my/repo"
```
## Structure
### Readme.md
The index is built as a nested list in the `readme.md`. It is located under
`## Index`. So your `readme.md` could look like this:
```markdown
# My Package
Hello World.
## Index
- ## Getting Started
- [Introduction](introduction.md)
- [Installation](installation.md)
- ## Foo
- [Bar](subfolder/bar.md)
```
## Table of Contents
The table of contents is built from all `##` and `###` headings under the `#`
heading. No link tag with a `name`attribute is needed. You can easily build your
markdown file as follows:
```markdown
# Title
## Introduction
...
```
## Configuration
With **Docdress** any number of repositories can be documented in one laravel
project. Each repository is configured in `docdress.repos` like so:
```php
'repos' => [
'my/repo' => [
// ...
],
],
```
The following attributes can be configured for a repository:
- `route_prefix` - The route prefix under which the documentation is
accessible.
- `default_page` - The default page
- `versions` - An array containing the branches that should be available in
the documentation.
- `default_version` - The current version.
- `subfolder` - The subfolder of the documentation.
- `theme` - The theme that should be used for this repo. Default value:
`default`.
- `access_token` - Personal access token for private repositories.
- `webhook_token` - Webhook token to allow pulling the repository after a
change.
Some of the attributes are discussed in more detail below:
### Versions
Every version is representing a branch. Set the `default_version` to your
default branch. The versions are specified as branch name and title, like so:
```php
'repos' => [
'my/repo' => [
// ...
'default_version' => 'master',
'versions' => [
'master' => 'Master',
'1.0' => '1.0'
]'
],
],
```
### Private repositories
Private repositories require a
[personal access token](https://github.com/settings/tokens) with the read
permissions for the repository.
```php
'repos' => [
'my/repo' => [
// ...
'access_token' => env('GITHUB_ACCESS_TOKEN', null)
],
],
```
### Subfolder
You may have the documentation of a project or a package in a subfolder of the
corresponding repository. If a `subfolder` is specified in the config, only this
folder is cloned and displayed.
```php
'repos' => [
'my/repo' => [
// ...
'subfolder' => 'docs'
],
],
```
### Webhook
If you want the latest version to be automatically updated with every push, you
have to set a webhook with the url `_docdress/update`.
Additionally the **Content-Type** must be set to `application/json`.
And the `token` from your config must be specified.
```php
'repos' => [
'my/repo' => [
// ...
'webhook_token' => env('GITHUB_WEBHOOK_TOKEN', null),
],
],
```
### Algolia
[Algolia Docsearch](https://docsearch.algolia.com/) can be used for the search
of your documenation. All you have to do is to specify your **application key**
for the respective repository.
```php
'repos' => [
'my/repo' => [
// ...
'algolia_app_key' => env('ALGOLIA_APP_KEY', null),
],
],
```
## Authorization
You may create gate for a repository in the `boot` method of your
`AuthServiceProvider` to manage access to the documentation.
```php
use Docdress\Docdress;
public function boot()
{
$this->registerPolicies();
Docdress::gate('my/repo', function ($user) {
return $user->is_admin;
});
}
```
## Alerts
You may display alerts just like custom-blocks in vuepress. The available alert
types are `tip`, `warning`, `danger`
```markdown
::: tip
Hello World!
:::
```
```markdown
::: warning
Hello World!
:::
```
```markdown
::: danger
Hello World!
:::
```
## Search Component
By using the `x-dd-search-input` component. You can place the algolia search
input in your blade views. The component needs the `repo` that should be
searched and the desired version.
```html
```
## Testing
Execute tests via composer:
```shell
composer test
```