tetrode/chalkmark

Render Markdown right in your terminal / CLI — headings, colors, lists, code blocks

1.0.1 2025-11-23 13:49 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^11

MIT

README

Render Markdown right in your terminal — headings, colors, lists, code blocks

Chalkmark supports

Chalkmark is a small PHP library that renders a large subset of Markdown to plain-text suitable for CLI output, with optional ANSI colors. It is designed to be lightweight and dependency-free. An example of the terminal output is shown at the end of this README.

It supports:

• Headings # ... ###### (levels 1–6)
• Horizontal rules as 40+ underscores on a line
• Unordered lists using -, *, or + (with indentation)
• Ordered lists like 1. or nested 1) … (with indentation)
• Paragraphs with inline formatting:
  • code using backticks: `code`
  • italic: *text* or _text_
  • bold: **text** or __text__
  • bold+italic: ***text*** or ___text___
• Code blocks fenced by backticks: ```code```
• Blockquotes using a pipe-prefix syntax: | quote with nesting like | | nested
• Tables using pipe syntax (GitHub-style). Table blocks are normalized: column widths are computed, cells are padded, and alignment markers (:---, :---:, ---:) control left/center/right alignment. The separator line is rendered with dashes only (colons are not shown).

Rendered output ends with a trailing newline and ensures there is a blank line at the end.

Overview

• Language/stack: PHP 8.2+
• Package manager: Composer
• Test framework: PHPUnit 11
• Autoloading: PSR-4
• Demo script: tests/show-fixture-markdown.php & tests/show-own-readme.php

Requirements

• PHP >= 8.2
• Composer (for installation and dev tooling)

Installation

This package is a Composer library. From a project that uses Composer, you can install it with:

composer require tetrode/chalkmark

Note: The package name is taken from composer.json (tetrode/chalkmark).

Usage

Minimal example rendering a file and printing to STDOUT:

<?php
use Chalkmark\Chalkmark;

require __DIR__.'/../vendor/autoload.php';

$renderer = new Chalkmark();
$renderer->displayFile(__DIR__ . '/README.md', STDOUT);

Customizing colors or disabling them:

<?php

use Chalkmark\Chalkmark;

$colors = [
    'h1' => "\033[1;34m",     // bright blue bold
    'bullet' => "\033[36m",   // cyan for list bullets
    'code_inline' => "\033[33m", // yellow for inline code
    // set any color key to '' (empty) to remove coloring for that element
];

$renderer = new Chalkmark($colors, $enableColors = true);

// Disable all colors (useful for logs or tests):
$rendererNoColor = new Chalkmark([], false);

Command-line demo

This repository includes a tiny demo script you can run locally after installing dependencies:

composer install
php tests/show-markdown.php
php tests/show-own-readme.php

Table example

Input:

| Left aligned | Centered | Right aligned |
|:-------------|:--------:|--------------:|
| Apple        | Red      |           10 |
| Banana       | Yellow   |            2 |
| Cherry       | Dark Red |            6 |

Output (no colors):

| Left aligned | Centered | Right aligned |
| ------------ | -------- | ------------- |
| Apple        |   Red    |            10 |
| Banana       |  Yellow  |             2 |
| Cherry       | Dark Red |             6 |

Environment variables

No environment variables are required or used by the library.

Running tests

PHPUnit is configured as a dev dependency. After composer install you can run:

./vendor/bin/phpunit

Tests include both behavior assertions and a demonstration that writes rendered output to the CLI.

License

Chalkmark is made available under the MIT License (MIT). Please see License File for more information.