README

Description

A library for generating markdown using PHP. This library provides a class for building markdown following the CommonMark specification. It also provides support for some common extensions including:

• Superscripts
• Subscripts
• Tables
• Strikethrough (Using ~~syntax~~)

Intallation

composer require ckunkle/markdownwriter

Example Usage

<?php
require_once("vendor/autoload.php");

$md = new \MarkdownWriter\Writer();
$md->h1("Example Markdown")
->p("This class makes generating markdown using PHP quick and convenient")
->ol([
    "Here is",
    "An ordered list",
    "With",
    [
        "Nested",
        [
            "Sublists"
        ],
    ],
])
->blockQuote("View the API documentation below to learn more features");

# Example Markdown

This class makes generating markdown using PHP quick and convenient

1. Here is
2. An ordered list
3. With
    1. Nested
        1. Sublists

> View the API documentation below to learn more features

For a more elaborate example, view the script that generated this README file.

API

Inline Methods

Methods that transform input to return a formatted markdown string

italic

Format italic string

$md->italic("test");

*test*

bold

Format bold string

$md->bold("test");

**test**

superscript

Format superscript

$md->superscript("test");

^test^

subscript

Format subscript

$md->subscript("test");

~test~

code

Format inline code

$md->code("test");

`test`

strikethrough

Format strikethrough

$md->strikethrough("test");

~~test~~

link

Format an inline link

$md->link("test", "http://example.com");

[test](http://example.com)

image

Format an inline image

$md->image("test", "path/to/file.png");

![test](path/to/file.png)

Block Methods

Methods that write to the markdown result

write

Append string to the markdown result

$md->write("A string of text");
$md->write(" Another string of text");
echo($md);

A string of text Another string of text

block

Write an EOL string if the markdown result is not empty, write the provided string, then write another EOL string. This keeps blank lines between consecutive block elements.

$md->block("A string of text");
$md->block("Another string of text");
echo($md);

A string of text

Another string of text

p

Writes a paragraph to the markdown result making sure that there are blank lines before and after.

$md->p("A string of text");
$md->p("Another string of text");
echo($md);

A string of text

Another string of text

nl

Appends an EOL string to the markdown result

$md->write("A string of text");
$md->nl();
$md->nl();
$md->write("Another string of text");
echo($md);

A string of text

Another string of text

//or pass an integer for multiple newlines
$md->write("A string of text");
$md->nl(2);
$md->write("Another string of text");
echo($md);

A string of text

Another string of text

h1

Write a header 1

$md->h1("Header");
echo($md);

# Header

h2

Write a header 2

$md->h2("Header");
echo($md);

## Header

h3

Write a header 3

$md->h3("Header");
echo($md);

### Header

h4

Write a header 4

$md->h4("Header");
echo($md);

#### Header

h5

Write a header 5

$md->h5("Header");
echo($md);

##### Header

h6

Write a header 6

$md->h6("Header");
echo($md);

###### Header

hr

Write a horizontal rule

$md->write("A string");
$md->hr();
$md->write("Another string");
echo($md);

A string
---
Another string

ulItem

Write an unordered list item. Optionally provide the number of tabs to prepend to it

$md->ulItem("Item1");
$md->ulItem("Item2", 1);
$md->ulItem("Item3", 2);
echo($md);

- Item1
    - Item2
        - Item3

olItem

Write an ordered list item. Optionally provide the number of tabs to prepend to it and the string to prepend it with (defaults to 1)

$md->olItem("Item1");
$md->olItem("Item2", 1);
$md->olItem("Item3", 2, "123");
echo($md);

1. Item1
    1. Item2
        123. Item3

ul

Write an unordered list. Use nested arrays to indicate nesting sublists.

$md->ul([
    "Item1",
    "Item2",
    "Item3",
    [
        "Subitems",
        [
            "SubSubItems..."
        ],
    ],
]);
echo($md);

- Item1
- Item2
- Item3
    - Subitems
        - SubSubItems...

ol

Write an ordered list. Use nested arrays to indicate nesting sublists.

$md->ol([
    "Item1",
    "Item2",
    "Item3",
    [
        "Subitems",
        [
            "SubSubItems..."
        ],
    ],
]);
echo($md);

1. Item1
2. Item2
3. Item3
    1. Subitems
        1. SubSubItems...

blockQuote

Write a blockquote. This supports a few different syntaxes:

$md->blockQuote("Pass a string for simple block quote...");
$md->blockQuote([
    "Or an array for",
    "a multiline block quote",
]);
$md->blockQuote(function($md) {
    $md->p("This blockquote uses a callback")
    ->p("This allows us to use the writer's functionality to create content")
    ->blockQuote([
        "including",
        "block quotes"
    ]);
});

> Pass a string for a simple block quote...

> Or an array for
> a multiline block quote

> This blockquote uses a callback
> 
> This allows us to use the writer's functionality to create content
> 
> > including
> > block quotes

codeBlock

Write a "fenced" code block. Accepts a string or array of lines. Optionally pass a language for syntax highlighting as the second parameter.

$md->codeBlock("echo('This is a code block');");

    ```php
    echo('This is a code block');
    ```

table

Write a table. This expects an array of arrays where the first array is the header row, and the following arrays represent table rows.

$md->table([
    ["col1", "col2", "col3"],
    ["val1", "val2", "val3"],
    ["val1", "val2", "val3"],
]);

|col1|col2|col3|
|----|----|----|
|val1|val2|val3|
|val1|val2|val3|

Configuration/Misc

All other methods

setEOL

Set the EOL string. By default this is set to PHP_EOL

eol

Get the EOL string

__toString

Returns the markdown result string