Skip to content


Subversion checkout URL

You can clone with
Download ZIP
This repository has been moved

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



A Humane Web Text Generator

A lightweight markup language that takes (almost) plaintext and converts it into well formed HTML.


There are two main branches in the repository that will be of interest, both of which can be installed via the Composer package management system.

master Has a multi-file, namespaced, PSR-0/1/2 compliant version of textile. Releases from master are tagged v3.5.x Requires PHP5.3+
2.5 Holds a single-file version of textile representing the v2.5.x releases. It is not PSR-0 compliant but attempts to follow PSR-1 and PSR-2 in other respects. Requires PHP5.0+

This is the README for the master branch.

Currently both branches are feature synchronised at the point they are tagged and new features and bugfixes will go into both branches (where possible) for the time being but this will change at some point in the future.

From time to time other branches may be present in the repository. These represent transient development or hotfix branches and should not be used for live sites/projects.

Installation & Usage

Installation via Composer & Its Autoloader

To start using textile in a composer based project you need to add netcarver/textile to your project’s dependencies and have composer take care of the installation and autoloading of the code for you. If you don’t already have a composer.json file in the root of your project you probably need to read something about composer before coming back here, creating your composer.json file and pasting one of the following examples into it;

    "require": { "netcarver/textile": "3.5.*" }

…if you require the latest stable release from the master branch. Or;

    "require": { "netcarver/textile": "3.5.*@dev" }

…if you want the most recent code.

Then open a command line window, switch to the root of your project and run composer install. Textile should be pulled into your project under a the vendors/ directory and an autoloader created for all the dependencies in your project. If you are already using Composer and have a composer.json file, just update your “requires” section with one of the above lines and run composer update from the command line.

You should now be able to create and use a textile parser…

require 'vendor/autoload.php';                  // Bring in the composer auto-loader
use Netcarver\Textile;
$parser = new Textile\Parser();                 // Create a textile parser
$out = $parser->textileThis('h1. Hello World!');

If you aren’t using composer, try this…

Manual Install & Include

Copy the contents of the src/Netcarver/Textile/ directory to a location of your choice within your project. If you are using an autoloader, you will need to update it to load the classes Parser, Tag and DataBag from the \Netcarver\Textile namespace. If you are not using an autoloader you will need to include the following in a suitable location in your project…

include "path\to\textile\Parser.php";
include "path\to\textile\Tag.php";
include "path\to\textile\Databag.php";

Adjusting the path as needed. Now you should be able to create a textile parser using a fully qualified namespace like this…

$parser = new \Netcarver\Textile\Parser($doctype); // $doctype explained later

Parsing Input

For input that you trust use the textileThis() method.

$output = $parser->textileThis($trusted_input);

If you are using Textile to format user-supplied input, blog comments for instance, use a textileRestricted() call…

$output = $parser->textileRestricted($untrusted_input);


Currently, PHP Textile can target either XHTML or HTML5 output with XHTML being the default for backward compatibility. If you need HTML5 generation, just do…

$parser = new Textile\Parser('html5');

…and you’ll get abbr instead of acronym and if you use alignment markers on your images you’ll have extra classes placed on them instead of xhtml’s align attribute.

Setting alternate glyphs

From v2.5 on, you can no longer use the legacy ‘txt_’ defines to override the characters textile will use when doing typographic substitutions. If you need to setup textile to do non-standard typographic substitutions then you need to call setSymbol('name', 'value'); to setup the symbol table before you call textileThis() or textileRestricted().

If you wanted to override the symbol output for the one-half typographic substitution from the standard ½ to something using the fraction-slash you could do it like this…

$parser = new Textile\Parser('html5'); // adjust if you need a different doctype
$out = $parser
    ->setSymbol('half', '1⁄2')  // Redefine the half symbol to use the fraction-slash character

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

Prefixing relative image paths

From v2.5 onward you can explicitly setup a prefix that will be added to all relative image paths. This might be useful if your application only allows users to reference images from a certain location like, say, an images directory. The setRelativeImagePrefix() method is now available to you for explicitly setting this if you need it.

$parser = new Textile\Parser('html5'); // target whatever doctype you need
$out = $parser
   ->setRelativeImagePrefix('prefix') // adjust 'prefix' as needed
   ->textileThis($article)            // format the article

Textpattern is one project that is known to use a relative image prefix.

Getting In Contact

The textile project welcomes constructive input and bug reports from users. You can contact me in several ways.

  • Open an issue on the repository for a feature request or bug.
  • If you are on IRC, feel free to drop into #textile on (webchat.)
  • Use the generic contact form.
Something went wrong with that request. Please try again.