Download the PHP package stanislas-poisson/kmark without Composer

KMark

[![CI][ci-badge]][ci] [![Release][release-badge]][releases] [![Packagist][packagist-badge]][packagist] [![PHP][php-badge]][packagist] [![License][license-badge]][license] [![Docs][docs-badge]][docs]

A Markdown to HTML converter written in PHP. It follows the original Markdown (with the usual GitHub extensions: tables, fenced code, strikethrough), and adds one thing to it: an id and CSS classes can be attached to an element, for example # Title {#myId .class1 .class2}. It is made for the web: the output is HTML.

Status: stable, 2.0.0. KMark was written in 2013 with a syntax of its own (bold with *x*, italic with -x-, links as [x]:(url), code between two lines of ~~). It now follows the Markdown that everybody writes, so a text written for Markdown renders as expected (#34). That is a breaking change: see Upgrading from 1.x.

Documentation

The [documentation site][docs] has this guide and the reference of every class, read from the source, for each released version (selector at the top right, next is main). Build it with cd docs && npm ci && npm run dev.

Requirements

PHP 8.3 or higher. There is no dependency.

Usage

Install it with Composer:

The same with an instance:

A Convert object never changes: withText() and convert() return a new one.

Output:

The blocks of the output are separated by a line break, and the HTML is the one of the usual converters (<p>, <ul>, <pre><code class="language-php">…).

Syntax

Headings

# to ######, with closing # if you like (## Title ##). A # needs a space after it: #hashtag is text. A heading can also be underlined, as in the original Markdown:

Text styles

***both*** is bold and italic. Bold and italic are the ones of the original Markdown, the strikethrough ~~x~~ comes from GitHub, and --x-- and the underline are KMark's (Markdown has none). An underscore inside a word is not a marker, so snake_case_name stays as it is, and C++ is not an underline.

The default elements are the plain HTML ones: <b>, <i>, <u> and <del>. If you want other elements (<strong>, <em>, <ins>, <s>) or classes (<span class="b">), set them with the option tags, see Options.

Code

A code span is between backticks. The same number of backticks opens and closes it, so a code can hold backticks: . The text is escaped, and nothing is read inside it.

A code block is between two lines of three backticks or more (or three tildes or more). The word after the opening line is the language, written as a class:

`

gives

Lines indented by four spaces (or one tab) are a code block too.

Quotes

A quote holds blocks: headings, lists, code, other quotes. A line of text without > right after a line of text goes on with it, as in the original Markdown.

Lists

A list is nested by indenting its items, with four spaces, or two under a bullet, or a tab. A list is loose when a blank line separates its items or the blocks of an item: its text is then in paragraphs. Otherwise the text is written without <p>. A numbered list starts at the number of its first item (<ol start="3">). Two kinds of bullets next to each other are two lists.

Tables

As on GitHub: a line of headers, a line of dashes whose colons align the columns, then the rows. The cells can hold emphasis, code and links, and \| writes a bar inside a cell.

:--- is left, ---: is right and :---: is the centre (style="text-align: …").

Links and images

Inline: [text](url "title"). By reference, with the definition on a line of its own, anywhere in the text:

<https://example.com> and <[email protected]> are links, and so are the bare http:// and https:// URLs (see the option autoLinks). A final ., ,, ;, :, !, ? or a closing parenthesis that the URL did not open is left outside the link.

Escapes

A backslash before a punctuation character writes it as it is: \*not emphasis\*. Before anything else the backslash stays: C:\Users.

Id and classes

This is what KMark adds to Markdown. Write {#id .class1 .class2}:

• at the end of a heading, a paragraph or a list item (after a space): # Title {#myId .class};
• right after a link, an image or a code span, with no space: [text](https://example.com){.external};

• on a line of its own right after any block, to give it to that block, a list, a quote, a table or a code block:

• after the language of a fenced code block: ` php use KMark\Convert; use KMark\Options; use KMark\Tag;

$options = new Options( autoLinks: false, allowedSchemes: ['https', 'mailto'], tags: ['bold' => new Tag('span', ['bold'])], );

echo Convert::toHtml('hello https://example.com', $options); //

hello https://example.com

`make help` lists every command. See [CONTRIBUTING.md](CONTRIBUTING.md) for the details.

## Roadmap

1. Fix the known bugs and clean the application ([#2](https://github.com/Stanislas-Poisson/KMark/issues/2)): done.
2. Add the missing features ([#3](https://github.com/Stanislas-Poisson/KMark/issues/3)): done.
3. Turn KMark into a Composer package with a configuration ([#4](https://github.com/Stanislas-Poisson/KMark/issues/4)): done, released as `1.0.0`.
4. Follow the original Markdown and keep the id and class rules ([#34](https://github.com/Stanislas-Poisson/KMark/issues/34)): done, released as `2.0.0`.

## Statistics

![Statistics of KMark][stats-card]

## License

[MIT](LICENSE). Copyright (c) 2013 Stanislas Poisson.

[ci-badge]: https://img.shields.io/github/actions/workflow/status/Stanislas-Poisson/KMark/ci.yml?branch=main&label=CI
[ci]: https://github.com/Stanislas-Poisson/KMark/actions/workflows/ci.yml
[release-badge]: https://img.shields.io/github/v/release/Stanislas-Poisson/KMark
[releases]: https://github.com/Stanislas-Poisson/KMark/releases
[packagist-badge]: https://img.shields.io/packagist/v/stanislas-poisson/kmark
[packagist]: https://packagist.org/packages/stanislas-poisson/kmark
[php-badge]: https://img.shields.io/packagist/dependency-v/stanislas-poisson/kmark/php
[license-badge]: https://img.shields.io/github/license/Stanislas-Poisson/KMark
[license]: LICENSE
[docs-badge]: https://img.shields.io/badge/docs-online-blue
[docs]: https://stanislas-poisson.github.io/KMark/
[stats-card]: https://raw.githubusercontent.com/Stanislas-Poisson/Stanislas-Poisson/main/assets/projects/kmark.svg