PHP based Markdown documentation viewer

Last update: Mar 31, 2022

Markdown documentation viewer

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

  • PHP7.3+

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.

  1. Create a folder in your webroot from which to serve the documentation.
  2. Create a composer project there.
  3. Require the package: composer require mistralys/markdown-viewer.
  4. Create a PHP file (index.php) as endpoint for the documentation.
  5. Paste the following code into the file
  6. Edit the list of files you wish to view.
  7. Point your browser to the file.


declare(strict_types=1);

use Mistralys\MarkdownViewer\DocsManager;
use Mistralys\MarkdownViewer\DocsViewer;

if(!file_exists('vendor/autoload.php')) {
    die('Please run composer install 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, '/url/to/vendor'))
    ->setTitle('Documentation')
    ->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 Mistralys\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 Mistralys\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 Mistralys\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 Mistralys\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 Mistralys\MarkdownViewer\DocsViewer;
use Mistralys\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:

  1. Clone the repository into a webserver's document root
  2. Run composer install in the package folder to install the dependencies
  3. Point your browser to the package folder's example.php file

GitHub

https://github.com/Mistralys/markdown-viewer
You might also like...

A super lightweight Markdown parser for PHP projects and applications.

A speedy Markdown parser for PHP applications. This is a super lightweight Markdown parser for PHP projects and applications. It has a rather verbose

May 31, 2022

A highly configurable markdown renderer and Blade component for Laravel

A highly configurable markdown renderer and Blade component for Laravel

A highly configurable markdown renderer and Blade component for Laravel This package contains: a Blade component that can render markdown a highly con

Aug 13, 2022

Easily add routes to your Laravel app by creating Markdown or Blade files

Laravel Pages This package lets you create pages using Markdown or Blade without having to worry about creating routes or controllers yourself. Essent

Jul 6, 2022

Render colored Markdown contents on console terminal

Render colored  Markdown contents on console terminal

cli-markdown Render colored markdown contents on console terminal Preview run demo by php example/demo.php Features support auto render color on termi

Jan 27, 2022

Generate pseudo-static pages from markdown and HTML files for Flarum

Flarum Pages Generator This is not a Flarum extension. This package provides a Flarum extender that you can use in the local extend.php to define cust

Feb 21, 2022

markdown wiki/blog

markdown wiki/blog

Kwiki markdown wiki/blog Usage Place your markdown files in the /wiki directory. Categories are directories and subcategories are subdirectories. If y

May 29, 2022

Symfony 5 bundle to easily create dynamic subpages with Markdown. Useful for help sections and wikis.

MarkdownWikiBundle This bundle allows you to create rich subpages in a Symfony project using Markdown. Pages are stored in a file cache and sourced fr

Apr 26, 2022

Gruik ! An open-source markdown note-taking web app. [ABANDONED PROJECT]

What is Gruik ? It's a free & open-source note-taking service. A space where you can store notes, tutorials, code snippets... by writing them in markd

Mar 31, 2022

Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io - Deprecation Notice This repository is deprecated! Daux.io has been moved to an organization, to guarantee future development and support. So

Jul 30, 2022

Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io Daux.io is a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It help

Aug 8, 2022

Parser for Markdown and Markdown Extra derived from the original Markdown.pl by John Gruber.

PHP Markdown PHP Markdown Lib 1.9.0 - 1 Dec 2019 by Michel Fortin https://michelf.ca/ based on Markdown by John Gruber https://daringfireball.net/ Int

Aug 5, 2022

Parser for Markdown and Markdown Extra derived from the original Markdown.pl by John Gruber.

PHP Markdown PHP Markdown Lib 1.9.0 - 1 Dec 2019 by Michel Fortin https://michelf.ca/ based on Markdown by John Gruber https://daringfireball.net/ Int

Aug 5, 2022

A PHP tool to generate templateable markdown documentation from the docblocks or type-hints of your codebase.

Roster Installation To install, simply require the package using composer: composer require

Sep 8, 2021

🍪 Write gorgeous documentation for your products using Markdown inside your Laravel app.

🍪 Write gorgeous documentation for your products using Markdown inside your Laravel app.

LaRecipe Write gorgeous documentations for your products using Markdown inside your Laravel app. LaRecipe 🍪 LaRecipe is simply a code-driven package

Aug 15, 2022

Docbook Tool for static documentation generation from Markdown files

Roave Docbook Tool Static HTML and PDF generator tool for generating documentation from Markdown files. Generates a deployable HTML file from Markdown

Aug 1, 2022

A package that uses blade templates to control how markdown is converted to HTML inside Laravel, as well as providing support for markdown files to Laravel views.

A package that uses blade templates to control how markdown is converted to HTML inside Laravel, as well as providing support for markdown files to Laravel views.

Install Install via composer. $ composer require olliecodes/laravel-etched-blade Once installed you'll want to publish the config. $ php artisan vendo

Jul 5, 2021

:dromedary_camel: Laravel log viewer

:dromedary_camel: Laravel log viewer

Laravel log viewer TL;DR Log Viewer for Laravel 5, 6, 7 & 8 (still compatible with 4.2 too) and Lumen. Install with composer, create a route to LogVie

Aug 15, 2022

:page_with_curl: Provides a log viewer for Laravel

:page_with_curl: Provides a log viewer for Laravel

LogViewer By ARCANEDEV© This package allows you to manage and keep track of each one of your log files. NOTE: You can also use LogViewer as an API. Of

Aug 6, 2022

Robot increase telegram post 👁‍🗨Telegram Fake Posts Viewer👁‍🗨

Robot increase telegram post 👁‍🗨Telegram Fake Posts Viewer👁‍🗨

Program Features - 📍 Very and stylish design. - 📍 It has glass buttons. - 📍 Has a professional management panel. - 📍 Has a user area. - 📍 Free di

May 30, 2022
A PHP tool to generate templateable markdown documentation from the docblocks or type-hints of your codebase.

Roster Installation To install, simply require the package using composer: composer require

Sep 8, 2021
Docbook Tool for static documentation generation from Markdown files

Roave Docbook Tool Static HTML and PDF generator tool for generating documentation from Markdown files. Generates a deployable HTML file from Markdown

Aug 1, 2022
A simple regex-based Markdown parser in PHP

Slimdown A simple regex-based Markdown parser in PHP. Supports the following elements (and can be extended via Slimdown::add_rule()): Headers Links Bo

Jul 27, 2022
PHP Documentation system.

PHP Documentation system Simple but powerful Markdown docs. Features Search within Markdown files Customizable Twig templates (Note: default design is

Jun 8, 2022
Better Markdown Parser in PHP
Better Markdown Parser in PHP

Parsedown Better Markdown Parser in PHP - Demo. Features One File No Dependencies Super Fast Extensible GitHub flavored Tested in 5.3 to 7.3 Markdown

Aug 11, 2022
Highly-extensible PHP Markdown parser which fully supports the CommonMark and GFM specs.
Highly-extensible PHP Markdown parser which fully supports the CommonMark and GFM specs.

league/commonmark league/commonmark is a highly-extensible PHP Markdown parser created by Colin O'Dell which supports the full CommonMark spec and Git

Aug 6, 2022
Convert HTML to Markdown with PHP

HTML To Markdown for PHP Library which converts HTML to Markdown for your sanity and convenience. Requires: PHP 7.2+ Lead Developer: @colinodell Origi

Aug 11, 2022
PHP Markdown Engine Support

PHP Markdown Version v1.x support all PHP version >=5.4 v2.x support all PHP version >=7.0 Cài đặt thư viện Thư viện này được cài đặt thông qua Compos

Jul 1, 2022
Rendering markdown from PHP code

JBZoo / Markdown Installing composer require jbzoo/markdown Usage Rendering Table <?php declare(strict_types=1); use JBZoo\Markdown\Table; echo (new

Dec 26, 2021
PHP Markdown & Extra

PHP Markdown & Extra An updated and stripped version of the original PHP Markdown by Michel Fortin. Works quite well with PSR-0 autoloaders and is Com

Jan 18, 2022