Configuration

Olodoc creates your documents by converting your existing markdown files. Before start to read configuration section make sure you have some .md files in your /data/docs/$version/$locale folder.

- myproject
  + bin
  + config
  - data
    - docs
        - 1.0
            - en
                index.md
                installation.md
            + tr

Your First Directory Tree

Your directory tree configuration file navigation.php is located in /config/olodoc/$version/ folder.

- myproject
  + bin
  - config
    - olodoc
        - 1.0
            navigation.php

Open your navigation.php file and create your first simple navigation.

/**
* Navigation index
*/
return [
    [
        'label' => 'Introduction',
        'url' => '/index.html',
    ],
    [
        'label' => 'Installation',
        'url' => '/installation.html',
    ],
]

Run generate command

composer olodoc:generate

If everything went well your .html files will look at like below.

- myproject
  + bin
  + config
  - data
    - docs
        - 1.0
            - en
                index.md
                index.html
                installation.md
                installation.html
            + de

Creating Folders

Olodoc has unlimited subfolder support but you need to physically create the folders first and also define the folders in your navigation.php file.

To create a new folder:

1. Create a folder in your data/docs/en/ folder. (In this example we created a folder named markdown-guide)
2. Open your navigation.php file and paste below the configuration.

/**
* Navigation index
*/
return [
    [
        'label' => 'Introduction',
        'url' => '/index.html',
    ],
    [
        'label' => 'Installation',
        'url' => '/installation.html',
    ],
    [
        'label' => 'Markdown Guide',
        'url' => '/markdown-guide/index.html',
        'folder' => '/markdown-guide',  // specify folder path
        'children' => [                 // put your pages here into the children array
            [
                'label' => 'Markdown Guide',
                'url' => '/markdown-guide/index.html',  
            ],
        ]
    ],
]

Each folder configuration needs to has folder and children key.The "folder" key points your folder path and "children" key contains of your markdown pages.

Creating Sub Folders

Each sub folder configuration needs to has folder and children key under the parent folder children key. Also, the path and url value of the subfolder must include the parent folder name as follows.

'folder' => '/markdown-guide/basic-syntax',
'url' => '/markdown-guide/basic-syntax/index.html',

In this example we created a sub folder called basic-syntax under the markdown-guide parent folder.

<?php
/**
* Navigation index
*/
return [
    [
        'label' => 'Introduction',
        'url' => '/index.html',
    ],
    [
        'label' => 'Installation',
        'url' => '/installation.html',
    ],
    [
        'label' => 'Markdown Guide',
        'url' => '/markdown-guide/index.html',
        'folder' => '/markdown-guide',
        'children' => [
            [
                'label' => 'Markdown Guide',
                'url' => '/markdown-guide/index.html',
            ],
            [
                'label' => 'Basic Syntax',
                'folder' => '/markdown-guide/basic-syntax',
                'url' => '/markdown-guide/basic-syntax/index.html',
                'children' => [
                    [
                        'label' => 'Basic Syntax',
                        'url' => '/markdown-guide/basic-syntax/index.html'
                    ],
                ]
            ],
        ]
    ],
];

Meta Tags and Titles

You can assign html meta tags to any configuration that includes a url key as shown in the following example.

<?php
/**
* Navigation index
*/
return [
    [
        'label' => 'Introduction',
        'url' => '/index.html',
        'meta' => [
            'title' => 'Introduction',
            'keywords' => 'intro, introduction, open source, document, generation, php',
            'description' => 'Olodoc is an open source documentation creation tool developed in PHP to create documentation from your foldered markdown files. It allows you to create and customize unique templates for your applications with the Bootstrap 5 CSS framework.',
        ]
    ],
];