mprince2k18 / markdown-previewer
PHP based viewer for Markdown files, to view them with fenced code highlighting and navigation.
Requires
- php: ^8.0
- components/jquery: ^3.6.0
- erusev/parsedown: >=1.7.4
- erusev/parsedown-extra: >=0.8.1
- mistralys/application-utils: ^2.2.8
- twbs/bootstrap: ^5.2.3
This package is auto-updated.
Last update: 2025-03-04 17:59:17 UTC
README
PHP based viewer for Markdown files, to view them with fenced code highlighting and navigation.
It is designed to be used for viewing markdown-based documentation files, in a fire and forget way. The layout is based on Bootstrap 4, and does not need any additional configuration.
Requirements
- PHP8.0+
Features
- Automatic jump navigation built using the document's headers.
- Easily switch between the available documents.
- Syntax highlighted fenced code blocks.
- Light and dark modes.
- Additional support for "1)" style ordered lists.
Installing
The package is made to be used as a dependency in a documentation project: Put it in a folder in a webserver, point it to some markdown files, and it will display them.
- Create a folder in your webroot from which to serve the documentation.
- Create a composer project there.
- Require the package:
composer require mprince2k18/markdown-previewer
. - Create a PHP file (
index.php
) as endpoint for the documentation. - Paste the following code into the file
- Edit the list of files you wish to view.
- Point your browser to the file.
<?php declare(strict_types=1); use Mprince\MarkdownViewer\DocsManager; use Mprince\MarkdownViewer\DocsViewer; if(!file_exists('vendor/autoload.php')) { die('Please run <code>composer install</code> first.'); } require_once 'vendor/autoload.php'; $manager = new DocsManager(); // Add all the files you wish to view here, along with // a title that will be shown in the UI. $manager->addFile('Title of the file', '/path/to/documentation.md'); // The viewer needs to know the URL to the vendor/ folder, relative // to the script. This is needed to load the clientside dependencies, // like jQuery and Bootstrap. (new DocsViewer($manager, 'vendor')) ->setTitle('Documentation') ->setSpaceName('The Code Studio') ->display();
Adding single files
Single files can be added using addFile()
. This allows specifying the
name that the file will be listed under in the UI.
use Mprince\MarkdownViewer\DocsManager; $manager = new DocsManager(); // Add a single folder, non recursive. $manager->addFile('Name of the file', '/path/to/file.md');
Adding folders
To add multiple files, use the addFolder()
method:
use Mprince\MarkdownViewer\DocsManager; $manager = new DocsManager(); // Add a single folder, non recursive. $manager->addFolder('/path/to/files'); // Add a folder and all its subfolders $manager->addFolder('/path/to/files', true);
By default, all files with the md
extension will be added. A different extension
can be specified using the third parameter:
use Mprince\MarkdownViewer\DocsManager; $manager = new DocsManager(); // Add all TXT files from a single folder, non recursive. $manager->addFolder('/path/to/files', false, 'txt');
NOTE: Adding files this way means you cannot specify file IDs (see "Consistent file permalinks"). Please double-check that this is okay in your use case.
Consistent file permalinks
By default, the viewer will create an ID for each file based on its absolute path on disk. This means that the ID will change if the file is moved at some point, or if the viewer is used on different systems. Sharing permalinks risks the links being broken at some point.
To avoid this issue, specify a unique file ID manually when adding single files:
use Mprince\MarkdownViewer\DocsManager; $manager = new DocsManager(); $manager->addFile( 'Name of the file', '/path/to/file.md', '(Unique file ID)' );
The ID can be any string; the viewer uses it to create the hash that is used in the UI to identify the files. This way, permalinks will always stay consistent.
Dark mode
To turn on dark mode, simply use makeDarkMode()
:
use Mprince\MarkdownViewer\DocsViewer; use Mprince\MarkdownViewer\DocsManager; $manager = new DocsManager(); // Configure the files (new DocsViewer($manager, '/url/to/vendor')) ->setTitle('Documentation') ->makeDarkMode() ->display();
Viewing the example
The bundled example is built exactly like the example above, and will display
this README.md
file. To get it running, follow these steps:
- Clone the repository into a webserver's document root
- Run
composer install
in the package folder to install the dependencies - Point your browser to the package folder's
example.php
file