textile / php-textile

Textile markup language parser for PHP

PHP-Textile

Textile reference | Live editor

PHP-Textile is a modern Textile markup language parser for PHP. Textile is a humane web text generator that takes lightweight, readable, plaintext-like markup language and converts it into well formed HTML.

Install

Using Composer:

$ composer require netcarver/textile

Usage

The Textile parser can be accessed through the Netcarver\Textile\Parser class. The class is highly configurable, and actual parsing happens with the parse method:

require './vendor/autoload.php';
$parser = new \Netcarver\Textile\Parser();
echo $parser->parse('h1. Hello World!');

Parsing untrusted input

If you are using PHP-Textile to format user-supplied input, blog comments for instance, remember to enable restricted parser mode:

$parser = new \Netcarver\Textile\Parser();
echo $parser
    ->setRestricted(true)
    ->parse('!bad/image/not/allowed.svg!');

In restricted mode PHP-Textile doesn’t allow more powerful formatting options such as inline styles, and removes any raw HTML.

Parsing single-line fields

If you are using PHP-Textile as a field-level formatter to parse just inline spans and glyphs, use the setBlockTags method to disable block tags:

$parser = new \Netcarver\Textile\Parser();
echo $parser
    ->setBlockTags(false)
    ->parse('Hello *strong* world!');

The above outputs:

Hello <strong>strong</strong> world!

Doctypes

Currently, PHP-Textile can target either XHTML or HTML5 output with XHTML being the default for backward compatibility. The targeted doctype can be changed via the setDocumentType method:

$parser = new \Netcarver\Textile\Parser();
echo $parser
    ->setDocumentType('html5')
    ->parse('HTML(HyperText Markup Language)');

Setting alternate glyphs

Textile’s typographic substitutions can be overridden with the setSymbol method. If you need to setup Textile to do non-standard substitutions, call setSymbol before you parse the input with parse.

$parser = new \Netcarver\Textile\Parser();
$parser
    ->setSymbol('half', '1⁄2')
    ->parse('Hello [1/2] World!');

The symbol names you can pass to setSymbol can be found here.

Prefixing relative image and link paths

Setting prefix might be useful if you want to point relative paths to certain consistent location:

$parser = new \Netcarver\Textile\Parser();
$parser
    ->setImagePrefix('/user/uploads')
    ->setLinkPrefix('/')
    ->parse('!image.jpg! "link":page');

Getting in contact

The PHP-Textile project welcomes constructive input and bug reports from users. Please open an issue on the repository for a comment, feature request or bug.

Development

See CONTRIBUTING.textile.

php-textile's Issues

Migrate notelists

Wrap table th row in thead and td row in tbody?

Wondering if it might be a good idea to wrap table headers in a thead and standard rows in tbody tag.

Some CSS frameworks, and indeed the way most people code, have extra styling based on thead and tbody.

Current

<table>
  <tr>
    <th>Header 1</th>
    <th>Header 2</th>
  </tr>
  <tr>
    <td>Row 1: Cell 1</td>
    <td>Row 1: Cell 2</td>
  </tr>
  <tr>
    <td>Row 2: Cell 1</td>
    <td>Row 3: Cell 2</td>
  </tr>
</table>

Example of proposed method:

<table>
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Row 1: Cell 1</td>
      <td>Row 1: Cell 2</td>
    </tr>
    <tr>
      <td>Row 2: Cell 1</td>
      <td>Row 3: Cell 2</td>
    </tr>
  </tbody>
</table>

Add basic block/image/glyph parsing + output

Migrate the block/image/glyph handling to the new framework

Allow substitutions

Several folks have asked for the ability to have textile do text substitutions or variable substitutions within the text of their textile documents.

Various formats for marking these substitutions have been cited, so the actual markup of any items for substitution will need to be definable by the environment using textile.

Ordered lists

Consider this:

How to make a PB&J:

# Gather bread, peanut butter, and jelly
# Slice the bread if necessary
# Assemble the sandwich
## Spread peanut butter on one slice of bread
## Put jelly on another slice
## Put the two slices together
# Enjoy

It yields:

How to make a PB&J:

1. Gather bread, peanut butter, and jelly
2. Slice the bread if necessary
3. Assemble the sandwich
    1. Spread peanut butter on one slice of bread
    2. Put jelly on another slice
    3. Put the two slices together
4. Enjoy

But this would be easier to read:

How to make a PB&J:

1. Gather bread, peanut butter, and jelly
2. Slice the bread if necessary
3. Assemble the sandwich
    a) Spread peanut butter on one slice of bread
    b) Put jelly on another slice
    c) Put the two slices together
4. Enjoy

Therefore, I am thinking of a modifier for numerated lists that determines the formatting with the following options:

• arabic numerals: 1, 2, 3, ...
• uppercase alphabet characters: A, B, C, ...
• lower-case alphabet characters: a, b, c, ...
• uppercase Roman numerals: I, II, III, IV, ...
• lowercase Roman numerals: i, ii, iii, iv, ...

and the following formatting types:

• suffixed with a period: "1.", "A.", "a.", "I.", "i."
• surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)"
• suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)"

But how to achive this in textile? Perhaps with a special directive that precedes the items:

How to make a PB&J:

# Gather bread, peanut butter, and jelly
# Slice the bread if necessary
# Assemble the sandwich
##a) 
## Spread peanut butter on one slice of bread
## Put jelly on another slice
## Put the two slices together
# Enjoy

Am I asking too much?

No autoalign classes for images without other explicit class/id attribute

This works as expected:

!<(foo)bar.png!

This doesn't:

!<bar.png!

Suspicion:

pba() tests for !empty($in) here and bails out if this test renders false.

Neither the new image alignment classes nor the old align=left|center|right attributes will show up when we do not force-populate $in with some class or id.

Add support for HTML5 elements

HTML5 will introduce multiple new elements that textile doesn't yet support.

Indention; stale variable

Hi Steve,

please look into commit 830b3dfc1b9089ccdc4a4125778b54a83d20621a. I think $a_classes is not really neeeded. Also tidies up indentation.

Robert

Continuation of lists

A new line breaks a list of items, but sometimes it cannot be avoided, like in this example with blockquotes:

# First,

bq. Avoid problems, and you'll never be the one who overcame them.
-- Richard Bach

# Second item, but will be numbered "1"

bq. There is no elevator to success. You have to take the stairs.

Perhaps something like #+ could be used to indicate that the list will be continued?

'protected static' method modifier requires PHP 5

See https://github.com/netcarver/textile/blob/b90ad6b73b3f5840453c9b8e06c6f27f49afa4f2/classTextile.php#L1370. Textpattern's minimum system requirements are still at PHP 4.

Colgroups cause a warning when closing pipe is missing.

Spotted by jsoo...

|=. Testing colgroup and col syntax
|:\5. 80
|a|b|c|d|e|

...issues a warning in the output but...

|=. Testing colgroup and col syntax
|:\5. 80|
|a|b|c|d|e|

...works cleanly.

Update docs: colgroup and span.

As noted here http://forum.textpattern.com/viewtopic.php?id=35244 the header docs need updating. Thanks Jeff.

Pre blocks with classes and nested code tag

If a user creates a Textile pre block by typing bc. blah blah blah then it actually creates a pre block with a code tag nested within it - which is fine.

But if a user wants to put class attributes on the pre block those same classes are also appended to the nested code tag. That can play havoc with styling and I can't see a reason why it should inherit the classes at all.

For example:

bc(code pretty). here's some code

Creates:

<pre class="code pretty"><code class="code pretty">here's some code</code></pre>

When it should really create:

<pre class="code pretty"><code>here's some code</code></pre>

Multiple footnotes

Apparently it is not possible to use multiple footnotes in 
one citation[1,2]. So I end up with something like[1][^,^][2], 
but I would like[1,2] better.

fn1. "textile 2.0":http://textile.thresholdstate.com/

fn2. "textile 2.2":http://textile.sitemonks.com/

Edit: the question of multiple footnotes has been discussed in the textpattern forum before and two different solutions were proposed.

Edit 2: In Redcloth, blanks are acceptable between the references like this:

Many newspapers reported on this[1] [2] [3]

fn1. www.nytimes.com
fn2. www.wsj.com
fn3. www.usatoday.com

feature: to set some global/user-defined sensible default values for attributes

As discussed on IRC:

Imagine it in the context of notelists/noterefs/notedefs, but this could be extended to Textile in general.
What if it could be possible to set some global/user-defined sensible default values for attributes (mainly, the class attribute), for different elements.

notelists are output, by default, like:

<ol><li><li>...</ol>

We have seen that you can add classes/id to them, like:

notelist(my_notelist):a. Cheese

But, if you have to do it on every notelist you (or worst, your clients) add to a site, you will probably won't do it.
To say it simple: it could be helpful to add default class or classes to elements.
So, for example, all notelists will render like:

<ol class="notelist"><li></li></ol>

This way, as it gets disambiguated from other ol elements, then it's possible (an easier) to hook them via your CSS or JS.

I would say the main goals for this feature (global/user-defined values for attributes on a per-Textile-element basis) are:

• to help the web developer to "isolate" or "disambiguate" some Textile-created generic elements ("it's not an ol, it's a .notelist")
• to avoid having to ask the end-user: "remember to add (notelist) to every notelist, so to have it styled/scripted properly"

This would probably need some kind of config file, and also, to set some kind of priority/cascade.

1. By default, Textile-created elements don't get any default value for attributes like class (which other attributes may benefit from this? Clearly, #id is not one of them).

2. Add global default values for attributes like class. This could be in some kind of config file.

3. Let the end-user, at the moment of writing/using Textile in his documents, define the value for the attribute (a question arises: should it override the default value set in (2)? or should it be added/concatenated to the default value set in (2)?)

HTML to Textile converter

Do you have a plan to add this functionality into you script? Or maybe you know good script which can do it?

Migrate lists

Potentially more difficult as the list handling code is extremely intertwined.

Feature: Automatic odd/even CSS class declaration for tr

Forum thread: http://forum.textpattern.com/viewtopic.php?id=37123

Me: Automatic odd/even CSS class declaration for tr are urgently needed as well.

Bloke: Isn’t CSS nth-child more widely adopted across browsers yet? (I don’t know as it’s not my field of expertise)

Me: Have to check that but still I have to check then how to make it work (switchable) in textile.

Add support for different quotation styles.

Although you can edit classTextile.php and set the kind of quotes you need, this isn't always convenient -- especially for multi-lingual documents where the quote marks used can change within either a set of documents or even within the same document.

Would be nice to be able to automatically select the correct open/close quote marks for the language currently being used.

Cannot smart-quote around XHTML tags.

Examples...

"<span>text</span>"

gives two open quotes instead of an open and a close.

This is a known issue within textpattern (issue 50) http://code.google.com/p/textpattern/issues/detail?id=50

Paragraph must end before list

Consider this unordered list:

*Colors*
* Red
* Green
* Blue

It is rendered as:

<p><strong>Colors</strong>
<ul>
  <li>Red</li>
  <li>Green</li>
  <li>Blue</li>
</ul></p>

but should be:

<p><strong>Colors</strong></p>
<ul>
  <li>Red</li>
  <li>Green</li>
  <li>Blue</li>
</ul>

To avoid this, you could add a new line before the list, of course. But shouldn't textile yield valid code in every instance?

Bug: br tag needed for line break

Forum thread: http://forum.textpattern.com/viewtopic.php?id=37123

(...)

PPS: Oh, and the textile table parser should support textile line breaks.

Migrate links

Invalid markup of multiple lines starting with dash

The textile class appears to have an issue with multiple lines starting with a dash (-), for example:

- fjfhfjhf
- fhfhfh
- hfhfhfhjdb

will get rendered as a single line in the html code (missing the break), with the first dash as a "-", the following two as a "&#8211"

Whether the first dash should be rendered as a "-" or a "&#8211" isn't the issue or query, it's the fact that they are rendered on one line instead of over three lines as intended.

Have tested with several versions of classTextile.php including the latest.

Should lists be allowed inside blockquotes?

Should this...

bq. * Red
* Blue

...which currently produces the following non-validating output that needs action...

<blockquote>
    <p> <ul>
    <li>Red</li>
    <li>Blue</li>
</ul></p>
</blockquote>

...Output this (option A)...

<blockquote>
    <p>* Red<br />
    * Blue<br /></p>
</blockquote>

...or this (option B)...

<blockquote>
    <ul>
    <li>Red</li>
    <li>Blue</li>
    </ul>
</blockquote>

Whilst HTML allows lists in blockquotes, should they be valid textile? Or should textile take the path of simplification and render this as straight paragraph text?

Link to a reference cannot use 0

As mentioned here using a zero as a link ref causes an empty href in a link.

Add 'xyz' blocks please.

Ok, I've received enough of these requests to get me to try out a new feature that allows you to extend textile's block handling by registering your own handlers.

You want an 'xyz.' handler -- no problem, you can add your own.

Look at the feature-block-plugins branch for how to go about extending textile via 'textplugs' -- textile style plugins. Brief documentation in extending textile.

The branch includes a directory 'textplugs-available\external' that has implementations of a couple of additional block level handlers ('hr.' and 'bcphp.') that I've been asked for before.

As always, feature- branches are for testing only, not for live deployment.

Definition lists

Last year definition lists were added to the textile syntax, adopting the MediaWiki system, like so:

; coffee
: Hot and black
; tea
: Also hot, but a little less black
; milk 
: Nourishing beverage for baby cows.
: Cold drink that goes great with cookies.

This results in:

<dl>
    <dt>coffee</dt>
    <dd>Hot and black</dd>
    <dt>tea</dt>
    <dd>Also hot, but a little less black</dd>
    <dt>milk</dt>
    <dd>Nourishing beverage for baby cows.<br />
Cold drink that goes great with cookies.</dd>
</dl>

And looks like so:

coffee

Hot and black

tea

Also hot, but a little less black

milk

Nourishing beverage for baby cows.
Cold drink that goes great with cookies.

However, with the popular Ruby version of textile, another syntax in employed:

- coffee := Hot and black
- tea := Also hot, but a little less black
- milk :=
Nourishing beverage for baby cows.
Cold drink that goes great with cookies. =:

At the RedCloth sandbox this is also converted into:

<dl>
    <dt>coffee</dt>
    <dd>Hot and black</dd>
    <dt>tea</dt>
    <dd>Also hot, but a little less black</dd>
    <dt>milk</dt>
    <dd><p>Nourishing beverage for baby cows.<br />
Cold drink that goes great with cookies.</p></dd>
</dl>

which is almost identical to the other output (but has additional p-tags in the last lines).

In my opinion, the Ruby syntax would have been the better choice for definition lists. It is easier to read (colon and semicolon are hard to distinguish on the screen) and understand, it would maintain compatibility with Ruby's textile, and textile is not indebted to the Media Wiki syntax, is it? Therefore, I would suggest changing the current definition lists' syntax into this.

abbr support

Currently abbreviations (3 or more consecutive capital letters) are automatically wrapped with I propose the tag should either replace or be an option to promote semantic code.

http://www.w3.org/TR/1999/REC-html401-19991224/struct/text.html#h-9.2.1
http://www.w3.org/TR/xhtml2/mod-text.html#sec_9.1.

Basic framework for parser and generators

inline style in lists

Hi,

just DLded the latest 2.3 release, and i think there's a bug with inline styles in list items.. try this textile markup:

* *strong*
* *strong* followed by plaintext..
* _emphasize_
* _emphasize_ *strong*
* _emphasize_ *strong* **bold**
* _emphasize_ *strong* **bold** __italic__ 
* _emphasize_ *strong* **bold** __italic__ .. now some plaintext..

i'm getting this HTML out:

<ul>
  <li>*strong*</li>
  <li><strong>strong</strong> followed by plaintext..</li>

  <li>_emphasize_</li>
  <li><em>emphasize</em> *strong*</li>
  <li><em>emphasize</em> <strong>strong</strong> **bold**</li>
  <li><em>emphasize</em> <strong>strong</strong> <b>bold</b> __italic__</li>

  <li><em>emphasize</em> <strong>strong</strong> <b>bold</b> <i>italic</i> .. now some plaintext..</li>
</ul>

i checked with 2.2 -> there it's fine..

cheers, Jan

Textile extensions

Hi,

I am looking for ways to customise and extend textile for my application. I am writing a custom application in PHP but i want the text markup to support the same syntax as the Redmine issue tracking system does.

Redmine uses a ruby implementation of textile plus a few extras i think.

The main one i'd like to see is when URLs are entered they are automatically turned into links - without any special syntax. Textile as default obviously only does this if you specify links like "Google":www.google.com.

The other things i want to do is turn numbers starting # (e.g #1234) into links to the relevent Redmine page - i can easily convert the #1234 into a URL (using preg_replace) and then i was going to let Textile convert that into a link.

Similarly i'd like to convert UNC paths into file links (file:///) so that users can click links in-page and it opens documents stored on the network filestore.

See my other post at textpattern http://forum.textpattern.com/viewtopic.php?id=37570

I posted there as i don't think github has a forum and i didn't really want to submit a feature request until i knew what i want isn't already available.

Thanks

Generate different kinds of output

Could textile be split into a generic textile parser and a set of output formatters? The default formatter would be HTML but others could target other languages (HTML5/pdf etc.)

Add rel="xyz" to text and image links

Textile lacks the ability to specify rel attributes on links and images. Would be nice if we could explicitly set these attributes to allow easier triggering of effects like lightbox or simply to do rel="nofollow".

pba() eats multiple class assignments

Input:

p(foo bar#baz). Lorem

Expected output, as in Textile 2.2:

<p class="foo bar" id="baz" >Lorem

Actual output:

<p>Lorem

Double nested lists give bad output.

An example of invalid results from straight (though invalid) Textile:

## Red
## Blue

(Spotted by JSoo.)

semantics: allow additional thead., tfooter, tbody., tcaption., tcolspan. with nested tcolgroup., etc.

Forum thread: http://forum.textpattern.com/viewtopic.php?id=37123

(...)

Last not least please think about a speaking textile table syntax (semantics). I am referring to the new Textile Table Syntax

(...)

Why not allow additional thead., tfooter, tbody., tcaption., tcolspan. with nested tcolgroup., etc.

TOC

The addition of notelist. suggests doing something similar for a table of contents based on header IDs. Rather than trying to make a proper nested list out of it, an expedient hack would be to give each item in the TOC a class based on the header level:

<li class="h1"><a href="#foo">Foo</a></li>
<li class="h2"><a href="#bar">Bar</a></li>

using just a class on block attributes for notedef breaks the note

As reported via IRC, there is a bug if just a class is used on notedefs

This one breaks:

note#list:name(class) blahblah

whereas

note#list:name blahblah 

or

note#list:name(class#id) blahblah

works fine.

span() regexp misses tail delimiter

Input:

<p>*foo*</p>

Expected output:

<p><strong>foo</strong></p>

Actual output:

<p>*foo*</p>

Proposed fix:

Add opening angle brackets to the "tail" part of the regexp used in span() to launch fSpan().

See https://github.com/rwetzlmayr/textile/commit/76171963dff02a66fb28005fbf75206800b42f48

Needs testing.

Related discussion at http://forum.textpattern.com/viewtopic.php?id=37559 and http://goo.gl/eanzF

Allow modifiers that span non-English quotation marks.

With input text that already has embedded non-English quotation marks, you cannot simply add simple markup like strong or emphasis within the quoted text.

Reported by Uli.

consistency on markup for noteref links and noterefs back-links

Noteref links output this markup:

<sup><a href="#note_cheese_fermier_161687"><span id="noteref_cheese_fermier_349896">1</span></a></sup>

While noteref back-links output this one:

<a href="#noteref_cheese_fermier_349896"><sup>α</sup></a>

My suggestion is to go with one of the two possible nesting:

<sup><a></a></sup> 

or

<a><sup></sup></a>.

Which one would be more semantically correct? I don't know

how to assign multiple classes?

Unless I'm missing something really really obvious (while having a brain infarction), how do I assign multiple classes to an element?
I thought that just separating them by a blank space would be enought, but not.
That is, this won't work:

h1(class1 class2). Heading!

Nor this:

h1(class1.class2). Heading!

If not possible yet, consider this issue a request :)

Allow multiple note lists.

Extend textile 2.2 notelists to allow multiple lists of items. Main driver for this being possible use with HTML5 sections whereby a notelist of all notes occurring in a section can be placed in the section (probably just at the end.)

Requested by Julian.

Use non-word chars as back-ref

Currently the char to start a back-ref list has to be a 'word' character (letter). It's not possible to make Wikipedia-style links using, say, the caret (because it's a special character in the notelist tag) or an up-arrow or 'dagger' or some other non-word entity.

When making single back-refs (i.e. only linking back to the first occurrence) it'd be cool to be able to specify such a symbol. I appreciate this might make things tricky if someone uses a non-word char and tries to link back to more than one reference (would it choose the next entity in sequence for the 2nd back-ref?) so perhaps this is not feasible.

Single quotes test case

The following produces a weird result...

Drag'n'drop

Rendered...

Drag’n‘drop

Looks like the regex needs a little TLC

Migrate tables

Feature: add em space (&8195;)

A feature request: substitute the em space when two space characters are used. Most applicable for use between sentences (see http://en.wikipedia.org/wiki/Sentence_spacing_in_language_and_style_guides).

I've put a commit in my fork and created a pull request.

$this->ver still at '2.2.0';

See https://github.com/netcarver/textile/blob/b90ad6b73b3f5840453c9b8e06c6f27f49afa4f2/classTextile.php#L350.

Centered table cells broken in Textile 2.2

|_. attribute list |
|>. align right|
|=. center |
|<>. justify |

The =. alignment should lead to a center aligned td cell. It now gives a caption.

Thanks PS.