textile / textile-spec Goto Github PK

Textile specification

textile-spec's Introduction

PHP-Textile

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&#8260;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.

textile-spec's People

Contributors

Stargazers

Watchers

Forkers

mst-textile anhel-strauke ymarquezr72

textile-spec's Issues

Handling ":" in href attribute

I've received a new issue on python-textile (textile/python-textile#27) which caused me to wonder what the appropriate course of action is. Essentially what it boils down to is: how should ":" be handled within an href on a link. I usually use txstyle.org for guidance on how to handle special cases, but in this case it seems we diverge and that python-textile seems a little more sensible.

Consider the following:

input: this is some text to "a link":test:1234
output from txstyle.org: this is some text to “a link”:test:1234
output from python-textile: this is some text to <a href="test%3A1234">a link</a>

Handling the text as a link is definitely better, but what should be done about the colon character? Is it correct to percent-encode it or should it be left alone to let the browser interpret it? I feel it should be noted that this is an issue for one user who has a bunch of custom url schemes, which he links to in textile/python-textile#27. I'll work with him in the meantime to find a way around it, but it seemed this is an instance where some guidance from the spec would be helpful.

Thanks.

Support non-semantic tags for underline, strike-through and teletype text

Currently there are variants for two of the inline formatting markers (* and _ for  and , respectively), that allow styling text in the same manner but without the semantic meaning that the primary markers are meant to convey — i.e., as bold () and italic ().

I believe it is reasonable to expect that the same behavior would also apply to the other formatting options that HTML supports in both semantic and stylistic variants, namely <ins>/, <del>/<s>, and <code>/<tt>:

semantic (single markers)	stylistic (double markers)
`foobar` → `<strong>foobar</strong>` ✅	`foobar` → `<b>foobar</b>` ✅
`_foobar_` → `<em>foobar</em>` ✅	`__foobar__` → `<i>foobar</i>` ✅
`+foobar+` → `<ins>foobar</ins>` ✅	`++foobar++` → `<u>foobar</u>` ❌
`-foobar-` → `<del>foobar</del>` ✅	`--foobar--` → `<s>foobar</s>` ❌
`@foobar@` → `<code>foobar</code>` ✅	`@@foobar@@` → `<tt>foobar</tt>` ❌

IMO Textile would be more consistent and predictable if all these combinations behaved the same way.

older syntax for the language attribute?

@jgarber,

I have just discovered that the standard way to specify a language in textile is [es] (although it doesn’t work with [grc] or [de-1901]).

I remember that there was a time in which language was marked as :en. Could you confirm this?

Many thanks for your help.

:lang for the whole document

is there a way in textile to add a :lang for the whole document?

List support for footnotes

The sun is reportedly hot,¹ just like freshly baked potatoes.¹ Ice is cold.²

¹ ² Ouch. I also want this to contain a list:

Item 1

¹ Brrr.

I'm looking to achieve this type of output. Is such a thing possible?

website cannot be found

@jgarber, I’m afraid that http://textileit.com cannot be found by my browser.

Do you intend to activate the site or am I missing something?

Support for HTML rel in hyperlinks

Some browsers and search engines use the rel parameter to know what pages are related to one another and in what way, I think it should be possible to specify this with textile markup. Ideally, any kind of HTML attribute should be possible to specify.