Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
This repository has been moved

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
test
.gitattributes
CHANGELOG.textile
README.textile
classTextile.php
composer.json

README.textile

TEXTILE

A Humane Web Text Generator

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

Branches

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 documentation for the 2.5 branch

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

Manual Install & Include

The only file that is necessary for the correct operation of Textile 2.* is classTextile.php from the root directory. To use it, just grab the latest raw copy of classTextile.php and save it into your project. Now you have the source file installed you’ll need to include the file and create a parser…

include "classTextile.php"; // adjust path the if needed.
$parser = new Textile();

Then, for input that you control, pass it to TextileThis(). Like so…

$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 );

Via Composer & Its Autoloader

To start using textile in your project you need to make your project depend upon netcarver/textile 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 projet create one and paste the following into it…

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

Then open a command line window, switch to thre root of your project and run composer install. Textile should be pulled into your project under a new 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 add the “netcarver/textile…” part to your existing “requires” section and run composer update from the command line. You should now be able to create and use a textile parser…

require 'vendor/autoload.php';
$parser = new Textile('xhtml');                  // Targetting XHTML
$out = $parser->textileThis('h1. Hello World!'); // $out now holds the XHTML version of the input.

Ok, now for a little more detail about setting up your parser.

Doctypes

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('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('html5'); // adjust if you need a different doctype
$out = $parser
    ->setSymbol('half', '1⁄2')  // Redefine the half symbol to use the fraction-slash character
    ->textileThis($article)
    ;

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('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 freenode.net (webchat.)
  • Use the generic contact form.
Something went wrong with that request. Please try again.