Laradocs - Online Documentation

Laradocs is a Laravel project that provides an online documentation application similar to https://laravel.com/docs

Laradocs allows you to import your markdown files from Github or write them yourself. It does not keep a history of changes, that's why we recommend using Github for your documentation.

Installation

Installing Laradocs is similar to installing any other Laravel application. You can clone or fork the repository on Github, or download a zip file. Once you have done so you will need to use composer to install all of the dependancies that comes with Laravel and Laradocs. You can do this with the following command, as long as you have sufficiant permissions.

composer install

Once Laradocs is installed you will need to change the permissions on the /storage and /bootstrap/cache folders. This will be different depending on your server. Laravel requires that those two folders and the folders underneath it are writable.

Environment File

If composer did not create a .env file you can copy the .env.example file. Please ensure that the composer install created a APP_KEY. if it did not you can use the following artisan command to generate one.

php artisan key:generate

Database

Laravel requires this file in order to run. You will need to configure the following settings in that file.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Once the settings have been saved you can run the migrations with the following command

php artisan migrate

User Setup

As Laradocs is still in development it does not include a full administration backend. However, you can use the make:user command to generate a user. To do this you run the following artisan command and just follow the on screen prompts.

php artisan make:user --password=Y

Content Administration

To manage your content you will need to log into Laradocs using the User generated by make:user.

Once logged in you can set up the Github integration, and create / maintain your documentation.

Versions

Since Laradocs is based on Laravel documentation. You will want to create a tag for your documentation. If you only have one "version" you can create a tag with "master".

Github Integration

Integrating into Github is fast and easy. You will need to log into Github and click on settings. On the left hand side click on Personal Access Tokens. Here you will create a new token with the following access

• repo Full control of private repositories
  • :status Access commit status
  • repo_deployment Access deployment status
  • public repositories

You will then take this token and store it in the Settings of Laradocs. This token will be used to talk to Github and pull down the repositories and their information.

Github Import

To import your markdown files from Github you will need to navigate to Import Files. From here you will want to fill in the following

Version = The version you want to import the files into (eg; master)
Repository Name = The repository name on github (eg; laradocs)
Repository Owner = The owner of the repository on github (eg; laracademy)
Branch = The branch from github you want to pull in (eg; master)
Folder in Repository = The folder of all your markdown files (eg; docs, can also be left blank if your respository is just markdown files)

This will import all of the files into your system. It will not automatically place them on the documentation unless you have already setup the navigation (sections/items). If in the version the application finds the same filename it will overwrite it / update it. This is a great way to have your documentation up to date. Keep the same markdown files and reimport them from Github to get the latest versions.

Sections

Sections are the main categories of the documentation. Looking at Laravel's documentation the sections are things like

• Prologue
• Getting Started
• Dev Environments
• Core Concepts
• etc ...

You can create a section by going to "edit navigation" on the version you wish to edit.

Items (Documents)

Once you have a section added you can create items. These items can either be a brand new document (one that you write) or from an existing document. If you already imported your documentation you will want to choose from an Existing document.

Support

Laradocs is unfinished and will be upgraded to the latest version of Laravel (at this time Laravel 5.4). There is still a lot of work to be done but you can send requests or bugs to [email protected].

Thank you

~ Mickey