Introduction

Projinom is a static site generator for software project documentation. It parses a directory of markdown files and creates a clean static site similar to documentation for Bootstrap.

Installation

composer require volktron/projinom

Usage

./vendor/bin/projinom build <source> <destination>

Setup

To create a new Projinom set of documentation, run the following command:

./vendor/bin/projinom init <destination>

Follow instructions on screen.

Initial Files

Upon completion of the init command, a directory located at the <destination> will now contain a file structure with markdown files, some configuration .php files, and a copy of the Twig based template for generating the .html output.

Configuration

In the root of the documentation materials, a projinom.php must be defined. This file must follow the following format:

return [
    'name' => '<the name of your project>',
    'type' => '<documentation>',
    'versions_directory' => '<versions>',
    'dist_path' => '<dist_path>',
    'header_links' => [
        [
            'label' => 'Github',
            'url' => 'https://github.com/<your project>'
        ]
    ]
];

Within the versions_directory, create folders for each version of your project you want documentation for.

Within each version, an index.php must be created to specify sections of documentation and their individual sections. It is defined in PHP (as opposed to JSON) to make preserving the order of each element easier to maintain. This also allows for programmatic generation of the data structure if desired.

For example:

return [
    'directory' => [
        [
            'name' => 'Getting Started',
            'pages' => [
                'Introduction',
                'Setup'
            ]
        ],
        [
            'name' => 'Tutorial',
            'pages' => [
                'Breakfast',
                'Lunch',
                'Dinner'
            ]
        ]
    ]
];

Each element in a pages array also corresponds to a markdown file, e.g. Breakfast will tell Projinom to look for a file named Breakfast.md.

Adding a Section

Adding a section to your documentation is simple:

Create a file

Create a file with the markdown extension, e.g. Adding a Section.md

Update index.php

Add the name of the file (without the extension) to the index.php of the version you are working in.

Before:

'pages' => [
    'Apple',
    'Orange',
]

After:

'pages' => [
    'Apple',
    'Orange',
    'Adding a Section'
]

Once this is done, rebuild the project and the new content will show up.

Markdown

Projinom uses Parsedown as its Markdown parser.

This means you can write Projinom documentation using the full gamut of the Markdown syntax. See the official Parsedown tests list for examples.

Syntax Highlighting

Projinom uses Prism as its syntax highlighter, with the following languages available by default:

• PHP
• Bash
• Javascript
• Typescript

Usage

In order to syntax highlight a block of code, simply use standard markdown syntax for code blocks, and make sure to specify which language it's in.

For example:

<?php echo "Hello, World!";

can be generated by:

> ```php
> <?php echo "Hello, World!";
> ```