Frequently Asked Questions ­ Textpattern CMS

FAQ: Full Listing

How To Contribute Patches

You can fetch the latest development source of Textpattern with Subversion (SVN). There are various SVN clients available, for multiple platforms. Tutorials for a couple popular choices can be found in Textpattern Documentation.

What follows is a quick style guide, to be followed when modifying Textpattern source files to make patches for submission.

Patch Style Guide

  1. Use UNIX (LF) line feeds/endings rather than Windows (CR+LF) or Mac (CR)1
  2. Use “Real” or actual tabs, rather than spaces1
  3. When naming your patch file, make the name descriptive, and include the current revision number. e.g. fix_category_bug_r1375.patch
  4. Create a new issue. Describe what your patch is for. Attach it, if possible, to your issue. If you’re unable to do so, upload it somewhere where it can be downloaded, and include a full url to the file.2


1 Every decent text editor should allow you to change your line feed and tab settings, as well as what you want your defaults for these two settings to be.

2 Patches can also be sent in to the public developers’ mailing list.

Widows and no_widow


Why does Textpattern insert a non-breaking space ( ) between the last two words of my article titles?

sIFR won’t work properly on my article titles.



For those who don’t know, in typesetting, a widow is a single word on a line by itself at the end of a paragraph and is considered bad style.

The solution is to insert a non-breaking space between the last two words of your headline. Widon’t

Widow handling in Textpattern

Textpattern includes such a feature in the core to deal with widows. There is a preference, “Prevent widowed words in article titles?” and several tags, such as recent_articles, make use of this preference as the default value for the attribute, no_widow.

Why do my articles load slowly?


When I have comments enabled, my individual article pages load more slowly than the rest of my site.


Go to:
Preferences > Advanced > Publish > Spam blacklists (comma-separated)

and remove if it is there.

If this does not resolve the problem, read up on Diagnosing Performance Problems.

This FAQ does not apply to:

  • Sluggish admin-side performance
  • Slow rendering of article list pages
  • Delays during a comment preview or comment post

Troubleshooting Feed Issues

The Basics

  • Use the feed validator if you suspect a feed problem. If the feed validator indicates that your feed is invalid, then please post its messages verbatim in your support request. Also, the URL you submit to the feed validator is your feed URL, not your homepage URL—the feed validator does not auto-detect feeds.
  • Post your Diagnostics results.
  • Post a feed URL. If there’s a specific feed which is malfunctioning, post its URL if at all possible. If you’re having problems on an intranet server, can you replicate the problem on a public server? It will help those who are troubleshooting to be able to see what’s really going on.

The feed validator reports I have a missing description element.

Make sure there’s something entered in the “Site slogan” field in your Preferences.

My feeds are empty or don’t contain the right articles.

Check the “Syndicate?” option, found on the “Sections” tab. Sections that have the “Syndicate?” option turned off will not show up in your feeds.

Safari RSS

Safari RSS does not appear to output a single useful error message. If Safari RSS is having problems with your feed, try the feed in another feed reader first, then try the feed validator. Most often, the feed is invalid, but Safari’s error message doesn’t leave any clue as to the nature of the problem with the feed. Also, Safari will automatically change the scheme from ‘http’ to ‘feed’. That’s fine, within Safari, but remember that everywhere else your feed URLs still need to begin with ‘http’.

My browser tries to download the feed when I click the feed’s link.

Depending upon your browser, this is the correct behaviour. More likely than not, your browser is not capable of displaying XML. As the feeds are sent with the correct MIME type, your browser offers to download the file, rather than just displaying the raw content.This is the correct behavior, and your feed should work in a proper feed aggregator.

How can I setup feed autodetection?

If you want feed aggregators and other tools to be able to autodetect your feeds, you’ll need to add tags like the following to the <head> of your main page:

<txp:feed_link format="link" flavor="rss" />
<txp:feed_link format="link" flavor="atom" />

"Notice: undefined variable.." and similar messages

When your Production Status is set to Debugging, it’s not uncommon to see PHP Notices similar to this:

Notice: Undefined index: permlink in 
	.../textpattern/lib/txplib_misc.php(412) : 
	eval()'d code on line 26

Debugging mode is intended for just that: debugging problems. If everything is working fine, there’s no reason to turn on Debugging.

Notices in debug mode are not unusual, and by themselves aren’t an indicator of something wrong. If the only symptom you have is that there are notices produced when Production Status is set to Debugging, then there’s nothing wrong, and you can safely ignore them.

By itself, with no other symptoms, a Notice is not a bug, so please don’t report it as such.

On the other hand, if something is failing to work, the messages produced in debug mode might be helpful in tracking down the source of the problem.

Subversion (now Github)

The Textpattern source code is maintained on Github. From there you can clone the repo, make changes to it and issue a Pull Request so we can merge your amendments in. You can also raise an issue if you find a defect or have a feature request.

There are beginner guides for using git but if you need any specific help that’s not answered elsewhere, head on over to the forum and ask your question there.

IMPORTANT: The remainder of this article is for historical purposes only. It is no longer current, so please ignore it.

The following assumes you have a properly installed copy of Subversion, and a working knowledge of the command line.

Warning: Textpattern-current is the developers’ working copy of the Textpattern source code. It includes the latest bug fixes and features, but the most recent updates have usually received only light testing. It is not recommended for use on a live site. Use at your own risk, make backups first, etc.

How do I fetch the current version of Textpattern?

> cd /path/to/txp
> svn co
A 4.x/textpattern
A 4.x/textpattern/license.txt
A 4.x/textpattern/tmp

How do I find out which subversion revision I have?

> cd /path/to/txp/4.x
> svn log -q -r BASE
r105 | zem | 2005-02-25 11:17:30 +1100 (Fri, 25 Feb 2005)

How do I find out what the latest available revision is?

> cd /path/to/txp/4.x
> svn log -q -r HEAD
r108 | zem | 2005-02-26 10:41:17 +1100 (Sat, 26 Feb 2005)

How do I update to the latest revision?

> cd /path/to/txp/4.x
> svn update
U textpattern/include/txp_prefs.php
U textpattern/lib/txplib_misc.php
U textpattern/_update.php
Updated to revision 108.

How do I see what’s changed between my last update and the latest revision?

> cd /path/to/txp/4.x
> svn log -r BASE:HEAD
r105 | zem | 2005-02-25 11:17:30 +1100 (Fri, 25 Feb 2005) | 1 line
fix date permlinks in recent_articles and some other tags
r106 | zem | 2005-02-25 14:34:22 +1100 (Fri, 25 Feb 2005) | 1 line
fix typo in get_uploaded_file() (thanks Manfre)
r107 | zem | 2005-02-26 10:33:18 +1100 (Sat, 26 Feb 2005) | 1 line
remove extra stripslashes
r108 | zem | 2005-02-26 10:41:17 +1100 (Sat, 26 Feb 2005) | 1 line
fix handling of Windows tempdir paths

How do I update to a specific revision, or revert to a previous revision?

> cd /path/to/txp/4.x
> svn update -r 105
U textpattern/include/txp_prefs.php
U textpattern/lib/txplib_misc.php
U textpattern/_update.php
Updated to revision 105.

What’s the best way to upload a copy of Textpattern-current to my web site?

> cd /path/to/txp
> svn export 4.x test

Then zip or tar the contents of /path/to/txp/test, upload it to your web site, and unzip/untar in the appropriate place.

Subversion export won’t overwrite an existing directory, so you’ll need to erase or rename /path/to/txp/test before each subsequent export, or use svn export --force 4.x test.

How do I submit a patch to the developers?

After editing files in /path/to/txp/4.x:

> cd /path/to/txp/4.x
> svn update
> svn diff > /path/to/txp/myfile.patch

…then email /path/to/txp/myfile.patch to the developers. Use a descriptive filename, including the current revision number (e.g. “fix_category_bug_r108.patch”). If your update includes new files, use svn add path/to/myfile.php to make sure they’re included in the patch.

Make sure you examine the patch file to ensure it doesn’t include any unintentional changes. In particular, whitespace differences (typically caused by a text editor converting tabs to spaces) can inflate the size of a patch. If that seems to be the case, try this instead:

> svn diff --diff-cmd diff -x -w > /path/to/txp/myfile.patch


While a patch may include changes to multiple files, each patch should include only one thing – one bugfix, or one new feature. If you have more than one independent bugfix or feature to submit, you should break them up and send them as separate patches.

Make sure each patch is against a clean copy of the current revision, i.e. it doesn’t include the changes submitted in previous patches. svn revert -R will restore a pristine working copy from the repository (this will overwrite your local changes, so back them up elsewhere first).


For those of you who use windows, there is a nice GUI client called TortoiseSVN – with a good user manual too. It-s a right-click menu integrated tool which makes your life easy if you don-t know too much about SVN.

Just install it, create an empty folder, and right click TortoiseSVN > Checkout… on the new SVN menu.

Point there to the URL of the repo you want to browse contents from, and you’ve got the repo contents on your directory.

You can do all things listed above with TortoiseSVN, but be sure to read the manual first.

Article tags cannot be used outside an article context

Article tags, such as permlink and body may only be used from within an article context, which is either:

  • within a form called by the article or article_custom tags
  • within an individual article page

The following PHP functions... are disabled

The following PHP functions (which may be necessary to run Textpattern) are disabled on your server…

This means your hosting company or server administrator has disabled one or PHP functions. Usually they do this in an attempt to tighten security.

Functions Used by Textpattern

The following functions are used by Textpattern. If your diagnostics page reports any of these as disabled, your copy of Textpattern might work unreliably, or not at all.

Name Use
apache_get_modules Helps determine whether clean urls could be used at setup, and for diagnostics info.
apache_get_version Helps provide diagnostics info regarding clean urls.
parse_ini_file Language features, even if English is used.
php_sapi_name Determines whether PHP is running as an Apache module or CGI. Used for sending header information appropriate to the platform.
php_uname Provides diagnostics info regarding the server’s operating system.
set_time_limit Makes sure PHP does not timeout before installation, updates (including language string changes), and file downloads can be completed.

If one of these functions has been disabled on your server, you should ask your hosting service provider to enable it, or seek more suitable hosting for your Textpattern website, as there is no real reason to disable them.

Functions Not Used by Textpattern

The following functions are not used by Textpattern 4.0.x releases. If your diagnostics page reports one or more of these functions as disabled, you may safely ignore it, as they will not affect Textpattern operation in any way.

  • apache_child_terminate
  • apache_getenv
  • apache_note
  • apache_setenv
  • chgrp
  • chown
  • close_log
  • debugger_off
  • debugger_on
  • define_syslog_variables
  • diskfreespace
  • disk_total_space
  • dl
  • error_log
  • escapeshellarg
  • escapeshellcmd
  • exec
  • get_current_user
  • getrusage
  • highlight_file
  • imagefilltoborder
  • ini_alter
  • ini_restore
  • leak
  • link
  • listen
  • mysql_pconnect
  • openlog
  • pack
  • passthru
  • pclose
  • pfsockopen
  • phpinfo
  • popen
  • proc_close
  • proc_get_status
  • proc_nice
  • proc_open
  • proc_terminate
  • putenv
  • readlink
  • set_socket_blocking
  • shell_exec
  • show_source
  • socket_… (i.e. socket_bind)
  • symlink
  • syslog
  • system
  • system_exec
  • virtual
  • wget

Other Functions

If you have any listed in the message but not listed here, create a new topic in the Troubleshooting forum and post the full diagnostics message.

UNIQUE and INDEX keys should not both be set..


phpMyAdmin says there’s an error on the txp_lang table: UNIQUE and INDEX keys should not both be set for column `lang`


This is a phpMyAdmin bug. The error message displayed by phpMyAdmin is incorrect. You should ignore it.

Safe Mode move_uploaded_file error


Warning: move_uploaded_file(): SAFE MODE Restriction in effect. The script whose uid is xyz is not allowed to access…
I get a move_uploaded_file error when trying to upload a file or image.


Your hosting company has set PHP’s upload_tmp_dir setting incorrectly. You’ll need to ask them to fix it.

The upload_tmp_dir setting must refer to a filesystem directory that is accessible and writable by the PHP server process. In Safe Mode, upload_tmp_dir must be within open_basedir. See here and here for technical information.

Fatal error: Maximum execution time..


Fatal error: Maximum execution time of 60 seconds exceeded in…


Some servers set a time limit on PHP scripts, to stop long operations from continuing indefinitely.

Some Textpattern functions can take several minutes to execute (specifically, uploading files and importing article data). This can sometimes exceed the default time limit set by hosting companies. Textpattern attempts to automatically raise the PHP script time limit where possible. If you’ve received a maximum execution time error, it means Textpattern was unable to raise its time limit, so you’ll have to do it manually.

The procedure for raising the time limit is system dependent. Please see the PHP manual for details, and check your hosting company’s documentation for more information.

Warning: tag context error


What does error_article_context mean?
What does error_comment_context mean?


Certain Textpattern tags are only intended for use in a particular context.

Article form tags work only in an article context. They refer to a single article, so they can only be used in a context that identifies one particular article. Specifically, they may be used on an individual article page template, or in an article form that has been displayed using a <txp:article ... /> or <txp:article_custom ... /> tag.

Article context tags will not work in an article list page template, because list pages are not associated with any single article.

Comment form tags may only be used in the form that is used to display each individual comment (usually named comments).

How do I tell if I've upgraded correctly?

Go to Admin > Diagnostics, and select ‘High’ in the Detail listbox. The pre-flight check should tell you if there are any files you forgot to update.

Warning: function has been disabled for security reasons


I get a PHP warning message: “Warning: parse_ini_file() has been disabled for security reasons..”
Warning: some function has been disabled for security reasons..


This means your hosting company or server administrator has disabled one or PHP functions that are used by Textpattern.

Usually they do this in an attempt to tighten security, perhaps after a flaw has been found in an old or poorly written PHP application.

Textpattern requires a fully functional PHP environment to work properly. PHP with arbitrary functions disabled is not fully functional.

Textpattern has an excellent security record. The development team regularly audits the code to check for potential security holes, particularly those that have been exploited in other PHP applications. To date, no known exploits have been released.

You should ask your hosting company to consider removing the block on those functions, particularly parse_ini_file, or at least provide an exception for Textpattern. Textpattern does not use parse_ini_file in an insecure manner. Disabling that function does not increase security.

If your hosting company insists on continuing to block functions, you should consider switching to a new host that provides a complete PHP environment.

How do I create a MySQL database?


I get an “Access denied for user” error during installation.
I get a mysql_connect error during installation.


As mentioned in the brief installation instructions, Textpattern requires a MySQL database and user to be created before installation.

The procedure for creating a database and user varies between hosting companies. Some hosts will create one for you. Others provide a control panel like cPanel or Webmin with a MySQL management section. You’ll need to read the documentation provided by your host for more information.

You don’t need to do anything other than create an empty database and a user with sufficient permissions to create and modify tables.

Once you have created or located your database, run the Textpattern installer and follow its directions. (See also: Detailed Installation Instructions.)

If you receive an “Access denied” or mysql_connect error during installation, it usually means that one or more of the MySQL parameters (host, database name, user name, password) are incorrect. Double check those values, and consult your hosting company’s technical support resources if problems persist.

Textpattern suddenly stopped working

Software doesn’t wear out or change by itself. If your copy of Textpattern stopped working, it’s because something on the server has changed. The most likely causes of sudden unexplained problems are:

  • Server upgrades and configuration changes. Check your hosting company’s news announcements or ask them if they’ve changed anything on your server recently. In particular, hosting companies have been known to upgrade MySQL versions or move databases without following the necessary procedures for ensuring data integrity.
  • Database or filesystem corruption. A server crash or hardware failure can cause data and files to be lost or corrupted. See this FAQ for more information about repairing a corrupt database.
  • Textpattern modifications or plugins. Have you installed a new plugin, Textpattern update, or modified one of Textpattern’s files recently? In some cases these changes can cause problems that aren’t noticed till some time later.

If your Textpattern site has suddenly stopped working, here are some steps you should take:

1. Check both the public web site and the Textpattern administration interface to see if they are working. Some problems affect only one or the other.

2. If you can log in to the Textpattern admin interface, view the admin > diagnostics page in both Low and High detail modes. Textpattern should report any major database corruption issues. See this FAQ for information on repairing these problems.

3. Check with your hosting company to see if they’ve upgraded or changed something recently, or moved your account to a new server.

4. If you can log in to the Textpattern admin interface, try disabling plugins one by one (on the admin > plugins tab).

5. Upload fresh copies of Textpattern’s files to your server, to replace any that might have been modified or damaged. This won’t affect content stored in your database. Make sure you upload all files in all subdirectories.

If none of these steps uncover the problem, you should raise a technical support ticket with your web hosting company.

Where can I see Textpattern in action?


What does Textpattern look like?
Is there an online demo I can try?
Where can I see some examples of Textpattern web sites?


There’s an online demonstration of Textpattern.

You’ll find Textpattern templates available for download and The preview galleries provide good examples of the range of page layouts and styles made possible by Textpattern’s template system.

Txp Magazine maintains a showcase of selected Textpattern powered web sites.

Why is my database corrupt?


Did Textpattern corrupt my database?
I have a corrupt database table, how do I fix it?


It’s possible for Textpattern’s database to become corrupted. There are several possible causes:

  • A server crash
  • Server hardware failure
  • A MySQL bug

It should not be possible for a user application like Textpattern to damage a MySQL table. (It might be possible for Textpattern to trigger a bug in MySQL, but the fault in that case lies with MySQL).

Occasional database corruption is a risk on shared hosting services, but should be rare. If you’re experiencing frequent corruption problems you should talk to your hosting company, and consider moving to a more reliable service.

In most cases a corrupt table can be repaired easily with little or no permanent damage. Many hosting companies and web hosting control panels provide a quick method of checking and repairing MySQL tables, so check their knowledge base and documentation.

The MySQL manual has a section on checking and repairing tables. TextDrive customers will find phpMyAdmin table repair instructions in the knowledge base.

There is also a Textpattern plugin which can allow you to repair tables in your Textpattern database.

In severe cases a corrupt table can cause data loss. You’ll need to restore a backup if this is the case.

What does the Production Status setting do?


What do the different Production Status settings change?
What are Debug, Testing, Live modes?


Textpattern’s Production Status setting (on admin > preferences) changes several aspects of Textpattern’s behaviour.

Live mode is intended for fully tested production sites.

In Live mode, all internal PHP error messages are suppressed, to eliminate the possibility of leaking sensitive information when something goes wrong. Browser caching features are enabled (4.0.4+ only).

Testing mode should be used when you are making changes to page templates, forms, CSS, configuration settings, or installing or updating plugins.

In Testing mode, PHP error and warning messages will be displayed to the user on public pages. Textpattern will attempt to warn about errors encountered in page templates and forms. Performance information will be included in HTML comments at the bottom of every Textpattern page. Browser caching is disabled.

Debug mode should be used for diagnosing problems in Textpattern templates, plugins and PHP code.

PHP notices will be displayed, in addition to the errors and warnings shown in Testing mode. A complete Tag Trace is included in HTML comments at the bottom of every page, listing all the Textpattern tags encountered on that page. Browser caching is disabled.

It’s normal to see some PHP notices in Debug mode. By itself, a PHP notice is not an indicator that something is wrong; it’s there to help PHP developers find potential problems.

Article text is cut off


I just edited an article, and the body text is cut off half way through.


We’ve had unconfirmed reports of some Firefox extensions causing problems with incomplete body text on the content > write tab.

If you’re experiencing this or similar problems, please test with browser extensions disabled, or try a different web browser.

Why can't I create a Forum account?


I tried signing up for the support forum, but never received a password email.
Forum thread subscriptions don’t work!


The most common cause of problems creating forum accounts are email spam filters and blacklists.

You must supply a working email address in order to create an account: when you sign-up, the forum software will send you the password you may use to login, to verify that your email address is correct and working properly.

Some email servers refuse to accept these emails, or incorrectly intercept them as spam. This is particularly common with free web mail services.

The following email providers seem to have problems accepting email from the forum, for one reason or another:


It is therefore recommended that you use an address from another provider.

Problems uploading images or files


I’m getting an error when I try to upload images or files using the Textpattern admin interface.
“Warning: move_uploaded_file() [function.move-uploaded-file]: SAFE MODE Restriction in effect.”
Does Textpattern work in PHP safe mode?


In order to use the Textpattern administration interface to upload images and files (via content > images or content > files), you’ll need to ensure Textpattern has access to the necessary directories.

Both image and file uploads require write access to a temporary directory. Textpattern attempts to find a writable temp directory during installation, and will automatically use it if one is found.

If no writable temporary directory was found, Textpattern will display a warning message on your admin > diagnostics page.

If you’ve recently moved Textpattern to a new server, you might need to alter the temporary directory setting to point to a new location.

To force Textpattern to search for a new temporary directory:

1. Go to admin > preferences > advanced preferences

2. Find the “Temp folder” setting, under “Admin”

3. Delete the contents of the Temp folder setting, and click the Save button.

If Textpattern is able to find a suitable temporary directory, it will automatically fill in the new setting. If the Temp folder setting stays blank, you’ll need to set it manually:

1. On the admin > diagnostics page, make a note of the Textpattern path setting. Typically it looks something like /home/foo/public_html/textpattern.

1. On your web server, using an FTP client, shell access or a file manager provided by your hosting company, find the tmp folder located inside the Textpattern path directory.

2. Change the permissions on this tmp folder to make it writable by the web server process. Your hosting company may provide specific instructions on this. On a Unix server, you may have to make the directory “world writable” by setting its permissions to 777, but before you do this, always consult your webhost, because 777 permissions are a serious security risk on shared webhosts and frowned upon in other hosting setups, so it’s safer to first try 700 or (if that fails) 711 or 755 permissions.

3. On the admin > preferences > advanced page, change the Temp folder setting to the full path to this tmp folder. If your Textpattern path is /home/foo/public_html/textpattern, that means your Temp folder setting should be /home/foo/public_html/textpattern/tmp.

Regardless of whether the temp directory is detected automatically or set manually, you’ll also need to make the files and images directories writable. These are located in the same parent directory that contains your Textpattern path – using the above example, /home/foo/public_html/images and /home/foo/public_html/files.

Using the same method described in Step 2 above, change the permissions on both of these directories to make them writable by the web server process.

Once the Temp folder is set correctly and writable, and the images and files folders are writable, file and image uploads should work correctly.

405 Method Not Allowed error


I get a 405 Method Not Allowed error when submitting a form
I get a 405 Resource Not Valid error when submitting a form


This is most likely a server configuration problem with Microsoft IIS. Textpattern itself never generates a 405 error.

You should ask your web hosting company to resolve the issue.

See this Google search for some discussion and possible solutions.

Errors during setup with MySQL 4.1.1


MySQL error during installation: “Specified key was too long. Max key length is 500”


This error is caused by a bug in MySQL 4.1.1.

MySQL 4.1.1 was an early test release, not a production version of MySQL. The first 4.1.x version deemed suitable for production use is 4.1.7.

Please upgrade your server, or raise a support ticket with your hosting provider and ask them to upgrade MySQL to a release version.

Client does not support authentication protocol


Warning: mysql_connect(): Client does not support authentication protocol requested by server; consider upgrading MySQL client..


This is a PHP error that occurs when the version of the PHP MySQL library is different to the MySQL server.

Please contact your hosting provider and ask them to fix the problem.

What kind of web sites does Textpattern do best?


Why should I use Textpattern?
How does Textpattern compare to other weblog/cms applications?
What does Textpattern do well?


We receive many questions about Textpattern’s strengths and limitations. Textpattern is best suited for web sites that require several — though not necessarily all – of the following features:

  • News or Weblog-style chronological articles, perhaps organized into several distinct departments or sections.
  • Groups of articles organized by other means, like a FAQ, product catalog or portfolio.
  • Single “static” pages, like an About or Contact page.
  • Images; either attached to articles (as in a photoblog), or displayed in a gallery.
  • File downloads.
  • Structure, presentation and content maintained separately.
  • Articles written by authors who don’t necessarily know HTML.

In other words, Textpattern is well suited for:

  • News, magazine, tutorial and review sites
  • Weblogs and photoblogs
  • Web sites for businesses and non-profit organizations
  • Online product catalogs
  • Portfolio and professional sites
  • Simple portals and file download sites

…or any web site that includes several of those characteristics.

You’ll find many fine examples of Textpattern sites on the Let’s See Yours, Then forum.

See also Can I use Textpattern to do this?

How do I do if_not_something?


Is there a <txp:if_not_... /> tag?


Textpattern includes a number of conditional txp:if_… tags.

All of the built-in conditional tags support the <txp:else /> tag. It works like this:

<txp:if_section name="about">
This section is "about"
<txp:else />
This section is not "about"

To do if not section, simply leave the first part empty:

<txp:if_section name="about">
<txp:else />
This section is not "about"

The same technique can be used with any <txp:if_...> tag.

I'm having trouble with a theme


I’m having trouble with the xyz theme..


Please ensure that you’ve followed the instructions that came with the theme.

If there are no instructions, or the instructions are incorrect, please contact the theme’s author.

Articles aren't showing up in XML feeds


Some articles aren’t showing up in my Atom/RSS feeds
The XML feeds for certain sections are empty


In order for articles to show up in an XML feed, they must:

  • be in a section that has “Syndicate?” set to Yes
  • have a status of Live (not Sticky)

Check the Syndicate setting for the relevant sections (see txp > presentation > sections), and the Status of the articles you’re expecting to see.

If that doesn’t help, try downloading a copy of the XML feed and viewing it manually. It’s possible that your news aggregator is choosing not to display some items, perhaps because it thinks they have already been read.

Firefox tries to download my RSS feed


When I click on the RSS link, my web browser tries to download it instead of display it.


Textpattern identifies its RSS and Atom feeds as “application/rss+xml” and “application/atom+xml” respectively. This is so that applications can distinguish between the different types of feeds without having to guess [1].

Different browsers handle “application/xml” in different ways. Mozilla and Firefox prompt the user with a file download dialog box.

The important thing to remember is that XML feeds are not web pages. They are not indended for viewing in a web browser.

[1]. The “old-fashioned” method was to identify feeds as “text/xml”. This merely identifies the document as XML, not as a news feed. Nor does it provide any way to distinguish between RSS and Atom, and can lead to character set encoding problems.

Common Textile Problems and Questions

Textile has been upgraded to version 2.0 as of Textpattern 4.0.4. Version 2.0 fixes many problems, and adds new features such as a bc. block modifier and extended blocks.

Some problems in earlier versions of Textile include:

Inline tags aren’t working

Inline tags like *bold*, _underline_ and ^superscript^ must normally be surrounded by whitespace (though trailing punctuation is usually fine).

A *bold* word -> “A bold word”.

A*bold*word -> “A*bold*word”.

This behaviour is intentional. Otherwise Textile would interfere with text like a name_with_underscores or vis-a-vis.

Textile 2.0, included in Textpattern 4.0.4 and higher, allows the following syntax:

A[*bold*]word -> “Aboldword”.

Textile won’t work with non-English characters, classes and styles don’t work

The new version of Textile fixes most of these problems.

Textile interferes with raw HTML in my article body

Textile tries to leave raw HTML alone. In most cases, an enclosed block of well-formed raw HTML like this will be left untouched:

<div class="foo">

However, blank lines within the block will result in unwanted <p>...</p> blocks and <br /> tags.

Blocks of HTML code that are completely enclosed by a tag will not be enclosed by <p>...</p> tags. A line that includes both HTML and unenclosed text will be processed as normal paragraph text.

To tell Textile to leave a block of HTML alone, use either the notextile.. block modifier, or leave a space at the beginning of each line:

notextile.. <div>

no textile here
p. Back to paragraph text.

If you’d like complete control over an article’s HTML markup, select Leave text untouched in the Article or Excerpt Markup box on the Write page, under Advanced Options.

Textile results don’t match

The version of Textile running on is very old.

imagejpeg() error when creating a thumbnail


Warning: imagejpeg(): Unable to access images/2t.jpg in textpattern/lib/class.thumb.php


This error messages is probably caused by a bug in PHP 4.4.1. It’s listed as fixed in the PHP 4.4.2 changelog.

Did someone hack my site?


I saw a bunch of suspicious hits in the Textpattern log. Is someone trying to hack Textpattern?
I think someone hacked my Textpattern web site!


Attempted security breaches are a daily occurrence at popular web sites. Vandals regularly scan thousands of web sites at a time for known security holes in common software. Only a small fraction of those sites will be vulnerable. On sites that aren’t, the only side effect will usually be a puzzling entry in the traffic log.

In 4 years, there have been no confirmed reports of a successfully exploited security hole in a properly maintained Textpattern web site.

There have been occasional reports of hacked Textpattern sites. In all cases these have been traced to security holes in other applications, or in the web server itself, which were used to take complete control of the user’s account. There is nothing Textpattern can do to defend against security holes in other applications. It’s up to you and your hosting company to keep your applications and server up-to-date with security patches.

The Textpattern development team takes security seriously. We don’t expect our record to remain perfect forever. But we do take a proactive approach to security, regularly auditing the Textpattern source code for potential holes. We don’t wait for the bad guys to find them first.

There are several steps you can take to maximize the security of your web site:

  • Keep your copy of Textpattern up to date.
  • Keep your plugins up to date.
  • Check the admin > diagnostics page for security warnings.
  • If you use other PHP or CGI applications in the same account, like a photo gallery or form mail application, make sure they are maintained and up-to-date.
  • Don’t leave test code or unused PHP/CGI applications on your server.
  • Pay attention to security announcements from your hosting company or server admin.
  • If you maintain your own server, keep it up to date with security patches.

Please note that the Textpattern development team has no control over the quality or security of plugins, add-ons and modifications. It’s up to you to evaluate the security of third-party code.

If you think you have found a security problem in Textpattern, please do not publish sensitive information until the development team has had time to respond. Information about potential security problems should be reported to security at textpattern dot com.

Publishing an article is very slow


There’s a long delay when I click the Publish button. Why?


This is probably caused by a delay in contacting A DNS problem on your server is the most likely cause.

You can confirm whether or not this is the problem by turning off “Ping ping-o-matic” and “Ping” in admin > prefs > advanced > publish.

Will you add my code to Textpattern?


I’m planning on writing a fantastic new feature for Textpattern. Will you add it to the core if I send you the code?
What criteria do you consider when adding new code and features?


We accept most, but not all code that is submitted for inclusion in the Textpattern core. Sometimes we’ll accept part of a patch, or include a modified or abridged version.

Textpattern is open source, so you don’t need our permission to make your own modifications or extensions. However, if you want to maximize the chances it will be accepted and included in the official distribution, here is a quick guide to the Textpattern development philosophy.

Do the simplest thing that could possibly work.

Is there a shorter or easier way to achieve the same result? Then do it that way. Less code means fewer bugs.

Don’t reinvent the wheel. Is there already a function in PHP or Textpattern that makes your job easier? Use it.

Minimize assumptions.

Don’t try to solve a problem unless you’ve tested it. This is particularly important for performance enhancements: measure the speed before and after – is the improvement really significant? If not, the simplest solution might be to leave it alone.

Similarly, don’t write a bunch of functions or tag attributes on the assumption that they might be useful in the future. Unless you have a use case, leave it out.

Make it testable

This is the most important part. The development team won’t include your code in the core unless they’re confident they can support and maintain it – after all, they’re the ones who will receive the bugs reports and cries for help. The more you can do to help test your code, the better: examples of input and expected output, a test plan, notes on what you have and haven’t tested.

Scripted unit tests are becoming increasingly important in the Textpattern release process. You can make your code more testable by using a functional design with minimal coupling. A function that can be run in isolation, and returns a value based on its arguments, is easy to test. A function that prints output based on global variables, database records and configuration values is much harder to test. (Conveniently, Textpattern tag handler functions are usually easy to test).

Sure, we break our own rules sometimes. But, as a rule, we err on the side of simplicity.

How do I get password-protected directories (with .htaccess) to co-exist with textpattern?


Using .htaccess authentication makes the directory inaccessible.
HTTP Basic Authentication with the webserver redirects everything to textpattern’s index page.
Using HTTP Auth with Apache results in 404 error pages.


Please add the following lines to your .htaccess file:

ErrorDocument 401 /[path_to_file]/myerror.html
ErrorDocument 403 /[path_to_file]/myerror.html

Make sure you point to existing, static html files.

Explanation: HTTP Basic-Auth first sends 401 Unauthorized to request a password from the browser. The webserver tries to serve the corresponding, specified Errordocument. However when the ErrorDocument directive of your webserver is set wrongly, i.e. points to a non-existent file, Textpattern ends up handling the page-request.

Also See:

Is Textpattern a CMS or a Blog?


Is Textpattern a CMS or Weblog application?


Opinions differ. The Textpattern developers believe that the distinction between “blog platforms” and “CMS applications” is mostly arbitrary: a weblog application is a CMS.

Textpattern is simple enough to be used as a weblog, and capable enough to be used as a CMS for business and news web sites.

Diagnosing template problems


My page template isn’t displaying what I expect!
My form isn’t displaying the right thing
This tag isn’t working!


We get many requests on the forum for help with template problems. Typically, these are caused by a few simple mistakes or misunderstandings. Below is a brief guide to diagnosing common problems. Please take the time to follow this before asking for help on the forum – it makes it much quicker and easier for others to answer your question.

When a page template doesn’t display the output you expect:

Check for error messages in Testing mode

Set your Production Status to Testing in textpattern > admin > prefs. Live mode suppresses all error messages for security reasons; Testing ensures they are displayed. Reload the page in question and look for errors.

If there is an error associated with a tag, the message should identify that tag.

One common error to check for is Warning: Missing argument 2 for .... This usually indicates a <txp:...> tag that hasn’t been closed properly.

If you see some other error message, search the FAQ and forum for more information, using the main keywords from the error message.

Check for template syntax errors

Some types of syntax errors in <txp:...> tags will cause a silent error. If your page is completely blank, or a large portion of it is empty, examine your template for XML syntax errors like the ones listed in this FAQ entry

Disable plugins

Sometimes a plugin can interfere with Textpattern’s normal operation. If you have plugins installed, try disabling them and see if it fixes the problem. Disable them one at a time and re-test the problem page after each so you can identify the problem plugin.

If you’ve identified a particular plugin as the culprit, the plugin forum is the best starting place to find help.

Double check the documentation

If you’ve isolated the problem to a particular tag, double check its documentation. Make sure the tag really does what you think (common errors include substituting <txp:article_custom /> for <txp:article />, and <txp:if_section> for <txp:if_article_section>), and ensure that the tag name and attribute names are spelled correctly and are lowercase.

Some tags work only in a particular context. Article Form tags, for example, work only in a form that has been loaded by a <txp:article form="myform" /> or <txp:article_custom form="myform" /> tag. Similarly, Comment Form, Link Form and File Download Form tags only work in comment, link, and file download lists respectively. Check the list of Form Related Tags to confirm that you’re using the tag in the right place.

Rule out CSS stylesheet problems

Sometimes a page template can be working perfectly, but appear to be incorrect due to a CSS stylesheet problem. Switch to a neutral stylesheet (perhaps the default style, or an empty stylesheet), and make sure that the unstyled content is correct.

If the stylesheet isn’t being applied to the document at all, or isn’t working in some browsers, view the HTML source of your page and find the CSS URL. Typically it looks like this:

<link rel="stylesheet" href="" type="text/css" media="screen" />

Open that URL ( in your browser and check for obvious problems – a 404 Not Found error, or error messages or other junk at the top or bottom of the stylesheet.

Isolate the problem code

Try simplifying your code and moving it to a fresh template, one small portion at a time. Start with a template that you know to be reliable – the default page is a good choice – and test one small block at a time.

If the problem still occurs on the clean template, you know it’s caused by that particular fragment of code. Try reducing the code to the smallest fragment that still produces the problem – this will make it easier to identify the exact cause.

If the problem occurs on the default page template with no changes at all, it’s not a template problem.

Check the tag trace

In Debugging mode, Textpattern appends a Tag Trace to the HTML output of each page. View the HTML source of the page, and scroll to the bottom. The trace looks something like this:

[Page: default]
<txp:linklist wraptag="p" />
[SQL (0.000112): select Form from `txp_form` where name` = 'plainlinks' limit 1]
[Form: plainlinks]
[SQL (0.000153): select * from txp_link where 1 order by linksort ]

Some things to check:

  • The lines [Page: default] and [Form: plainlinks] indicate that a particular page template or form has been loaded. Make sure it’s the right one.
  • Is the code in question shown in the tag trace at all? If not, it might have been excluded by a conditional tag (<txp:if_...>).
  • If the problem code is in an article form, link form or comment form, is it being loaded? There might not be any articles/links/comments to display at all. The SQL query for the preceeding tag might give you a hint.

Can I use multiple CSS stylesheets?


How do I include several CSS stylesheets on a page?
How do I link to a style by name?
How do I use a CSS stylesheet for printing?


The standard CSS stylesheet link in the default template looks like this:

<link rel="stylesheet" href="<txp:css />" type="text/css" media="screen" />

The <txp:css /> part tells Textpattern to use the stylesheet associated with the current section (see presentation > sections).

You can link to additional stylesheets on the same page by referring to them by name. Create another style (under presentation > styles) and add an extra line to your template like this:

<link rel="stylesheet" href="<txp:css name="my_style_name" />" type="text/css" media="screen" />

The name parameter specifies the name of the stylesheet. Read more at Textpattern Tag Reference: css.

To add a print-only stylesheet, create one named print and add this to your page template:

<link rel="stylesheet" href="<txp:css name="print" />" type="text/css" media="print" />

How do I make links open in a new window?


How do I add a target attribute to links?
How do I add a rel attribute to links?


You can use the PR Block plugin to add rel, target and similar attributes to links.

Here’s a simple method of making all links contained within an article body open in a new window:

<txp:zem_prblock target="_blank">
<txp:body />

The plugin will modify any <a href=...> tags it encloses, so you can wrap the zem_prblock tag around a txp:linklist tag, for example.

For a standards-compliant solution, use the PR Block plugin to add a rel="external" attribute to links:

<txp:zem_prblock rel="external>

Then use javascript to make all rel="external" links open in a new window.

Can I use tags within tags?


Can I use one tag as the attribute to another tag?


Textpattern supports nested tags — that is, enclosing one tag within another. For example, from the default article form:

<txp:permlink><txp:title /></txp:permlink>

It is also possible to use one tag as an attribute for another by embracing the attribute with single quotes:

<txp:article_custom section='<txp:section />' />

Single quotes serve as an indicator to Textpattern that it should feed the result of the embedded tag into the outer tag’s attribute, as opposed to the literal text which is used by embracing an attribute value with the usual double quotes.

See the weblog post on Textpattern’s tag parser for an in-depth explanation.

Problems with code in article bodies


My PHP code doesn’t work properly in an article body
My Javascript code doesn’t work properly in an article body


It is possible to put PHP and Javascript code directly inside an article body (there are some security settings for PHP code).

However, there are some limitations. Textile—the article markup used by Textpattern—doesn’t understand PHP or Javascript syntax, so it can’t always tell where the code starts and ends. This means Textpattern might try to interpret part of your PHP or Javascript code as Textile markup, which will almost certainly prevent it from working.

If you have more than a few lines of PHP or Javascript code, don’t put it directly in an article body. Instead, paste it into a new form of type “Misc”, and use the following tag to call the code:

<txp:output_form form="my_js_code" />

If you often find yourself calling code from article bodies, you might consider rethinking your design. Articles are for content, code is more appropriate for a page template or form. See if you can place the code in your article form instead.

Occasional "Database Unavailable" errors


Occasionally I see a “Dabatase Unavailable” error. Why?
Occasionally I see a “500 Internal Server” error, then it returns to normal..


Intermittent errors like these are usually caused by an overloaded server.

Database Unvailable means Textpattern is unable to connect to the SQL database. This can happen occasionally on some shared/virtual hosting servers when another user hogs all the available database resources. If it happens regularly, ask your hosting company whether there’s something they can do to fix the problem.

A 500 Internal Server error could mean any number of things, from a server misconfiguration to a major crash. Occasional intermittent 500 errors can happen on shared/virtual hosting servers when another user hogs all the available memory, cgi processes, or some other limited server resource. Again, talk to your hosting company if it happens regularly.

If you’re seeing Database Unavailable or 500 Internal Server errors on every page view, without exception, then the problem is most likely a database server crash, or a misconfiguration. In some cases we’ve seen hosting companies change important database or server settings without informing their customers first.

If this is the case, check the settings in your textpattern config.php file and make sure you can connect to the database using those settings in phpMyAdmin or similar. If the database server is working, check your .htaccess file, and consider temporarily disabling it. If problems persist, talk to your hosting company.

if_category vs. if_article_category


What’s the difference between <txp:if_category> and <txp:if_article_category>?
<txp:if_category> doesn’t seem to work!


The txp:if_category tag refers to the URL of the current page – i.e. the ?c=mycategory part, if it’s present.

The txp:if_article_category tag refers to the categories associated with the current article in an article list or on an individual article page.

Common "How Do I?" questions

Here are some quick answers to common “How Do I?” questions.

How Do I..

…display something only on an individual article page?

Surround it with an txp:if_individual_article tag:

	<!-- displayed on individual article page only -->

…display something only on list (section/front) pages?

Surround it with an txp:if_article_list tag:

	<!-- displayed on list pages only -->

…make an “About” page?

FAQ: Managing Static Pages

…make a reusable sidebar, header or footer?

With the txp:output_form tag.

FAQ: How do I reuse chunks of HTML?

…show a list of recent articles or comments in a sidebar?

With the txp:recent_articles or txp:recent_comments tags.

For more control over a list of recent articles, use txp:article_custom instead.

FAQ: How do I change the output of txp:recent_articles?

…show a short list of articles or article links in a sidebar?

For simple lists, the recent_articles tag might do what you want (see above).

To list articles from a specific section or category, use the txp:article_custom tag. Create an article form containing only the tags you want, for example:

<h4><txp:permlink><txp:title /></txp:permlink></h4>

<txp:excerpt />

Then use a tag like <txp:article_custom limit="5" form="myformname" /> in your sidebar.

…show a short version of articles with a “read more..” link?

Use something like this in your article form:

	<!-- excerpt only -->
	<txp:excerpt />
	<txp:permlink>read more..</txp:permlink>
<txp:else />
	<!-- full article body -->
	<txp:body />

FAQ: How do I show only an excerpt in article lists?

Excerpts automatically generated from the article body are possible through plugins.

…break an article list into columns, or insert ads between certain articles in a list?

Use the limit, offset and pageby attributes of txp:article:

<txp:article limit="3" pageby="10" />

<!-- column break or advertisement -->

<txp:article limit="7" offset="3" pageby="10" />

Textpattern Support Forum: txp:article pageby attribute

…supply a special layout to the first article on a page?

Use the txp:if_first_article tag in your article form:

	<!-- display the entire first article -->
	<txp:body />
<txp:else />
	<!-- display the excerpt only for subsequent articles -->
	<txp:excerpt />

…apply a special layout to articles from a particular section when shown on the front page?

Use the txp:if_article_section tag in your article form:

<txp:if_article_section name="linklog">
	<!-- "linklog" section only -->
	<div class="linklog"><txp:body /></div>
<txp:else />
	<!-- all other sections -->
	<txp:title />

	<txp:body />

…apply a special layout to articles from a particular category?

Use the txp:if_article_category tag in your article form:

<txp:if_article_category name="national">
	<!-- "national" category only -->
	<div class="linklog"><txp:excerpt /></div>
<txp:else />
	<!-- all other categories -->
	<txp:title />
	<txp:body />

…show a unique intro paragraph on each section page?

Post a “Sticky” article in each section containing the paragraph for that section, and display it with a <txp:article status="sticky" /> tag.

FAQ: How do I keep a post at the top of the page?

…show the same intro paragraph on more than one section page?

Post a “Sticky” article containing the text, and display it with the tag <txp:article_custom id="123" />, where 123 is the ID number of the sticky article. Enclose it with the <txp:if_article_list> tag if necessary.

FAQ: How do I keep a post at the top of the page?

…show a unique banner image or similar on a particular section page?

If the page layout for each section is to be identical except for a small element, you should probably share the same page template between all sections, and use the txp:if_section tag to selectively display variations:

<txp:if_section name="weather">
	<img src="/images/cloud.jpg" />

<txp:if_section name="sport">
	<img src="/images/cricket.jpg" />

<!-- etc -->

…add a stylesheet for printing?

Create a new style named “print”, and add this to the <head> portion of your page template:

<txp:css format="link" media="print" n="print" />

…display a random article, or a link to a random article?

Put this in your page template:

<txp:article_custom sort="rand()" limit="1" form="random" />

..and create an article form named “random” containing the appropriate article tags, e.g:

<txp:permlink><txp:title /></txp:permlink>

<txp:excerpt />

…display articles in a different order?

To sort by title in ascending alphabetical order:

<txp:article sort="Title asc" />

To sort by Category 1 in descending order:

<txp:article sort="Category1 desc" />

To sort by Category 1 first, then article date:

<txp:article sort="Category1 asc, Posted asc" />

To sort by a custom field1:

<txp:article sort="custom_3 asc" />

…display “Top Stories” first, then regular articles?

Use a custom field to identify your top stories, and use this tag in your page template:

<txp:article sort="custom_5 asc" />

Storing numbers in custom field 5 will bring articles to the top, with higher numbers shown first.

1 You must use the custom_n name here, not the custom field name as defined in Advanced Preferences.

Individual article pages don't respond


My article list pages work fine, but some individual article pages time out
When I try to view an article page with comments, the page doesn’t load


Are you using a Gravatar plugin? These and similar problems can occur when the Gravatar web site is down.

Disable the plugin and see if it makes a difference.

Search result troubleshooting


My site search isn’t returning the correct results.


Some common issues with searching:

Blank page

If your search results page is completely blank (a zero byte page), the problem is probably a fatal error that is not displayed because of your Production Status setting. See this FAQ for more information.

Page layout is displayed, but no articles

If your search results page shows its normal page layout, but with no articles, you should check three things:

1. That the sections containing the articles in question have Include in site search set to Yes on textpattern > presentation > sections.

2. That the search term you’re using really does match some articles. Test the same search term in the Search Body & Title box on textpattern > content > articles, and make sure that finds at least one Live article. If not, use a single, common word, and try varying the case. Case sensitive search results are caused by an incorrect collation setting on your textpattern database or table.

3. If you’re using a special section such as /search/ to display your search results, make sure your <txp:article /> tag doesn’t
specify searchall=0 – this will force it to look for articles in the search section. searchall=1 is the default; this tells the article tag to display results from all sections that have Include in site search set to Yes.

Wrong articles are displayed

If your search results page displays the wrong articles – the same articles as your front page, for example – it’s probably because you’re using the <txp:article_custom /> tag instead of <txp:article />. article_custom is context insensitive – that is, it always displays the same list of articles, regardless of the URL or query parameters.

Either change your page template to use <txp:article /> instead, or use a separate section and template to display the search results.

Does Textpattern support Trackback?


Does Textpattern support Trackback or Pingback?



We investigated the possibility of supporting Trackback, and concluded that it simply can’t be done securely. Trackback is 98% pure spam, and there’s no way to secure it.

It would be relatively easy for someone to develop a Trackback plugin. There appears to be very little demand, however.

How do I show a list of related articles?


How do I display a list of articles related to the current one?


Use the txp:related_articles tag in your page template or article form.

<txp:related_articles /> will list articles in the same category as the currently displayed article.

What languages does Textpattern support?


Can I write articles in my language?
Can I write articles in different languages?


Textpattern’s administrative interface has been translated to more than 40 languages – see below for a list.

You’re not limited to writing articles in those particular languages. Textpattern uses UTF-8, so you can write articles and create page templates in any language represented by Unicode. There’s no magic trick to this: just make sure your browser supports UTF-8, and write away. You can mix languages within an article — for example, quoting some French text in a German article, or using characters from other languages in an English article, as demonstrated in the list of languages below.

Textpattern doesn’t directly support articles with multiple translations. You can use sections or categories to organise a multilingual site. If you use one section to represent each language, you’ll be able to assign a specific template and/or CSS stylesheet to each, which might be helpful if some languages have specific layout requirements. If you’re already using sections for your site structure, create categories to represent languages.

To use a language with right-to-left text direction, such as Arabic, you’ll need something like this in your CSS stylesheet:

body {
direction : rtl;
text-align: right;

Textpattern translations as of 4.0.7:

  • جزائري عربي
  • Български
  • Bosanski (Bosna i Hercegovina)
  • Català
  • Čeština
  • Dansk
  • Deutsch
  • Ελληνικά
  • English (Great Britain)
  • English (United States)
  • Español
  • Eesti
  • Suomi
  • Français
  • Galego
  • עברית
  • Hrvatski
  • Magyar
  • Bahasa Indonesia
  • Íslenska
  • Italiano
  • 日本語
  • 한국말 (대한민국)
  • Latviešu
  • Nederlands
  • Norsk
  • Polski
  • Português (Brasil)
  • Português (Portugal)
  • Română
  • Русский
  • Slovenčina
  • Srpski
  • Српски
  • Svenska
  • ไทย
  • Türkçe
  • Українська
  • Tiếng Việt (Việt Nam)
  • 中文(简体)
  • 中文(繁體)

Can I make an image gallery?

If you want to display images with descriptions or comments, see Can I use Textpattern for a photoblog?

You can construct a simple image gallery like this:

1. Copy the default page template. Call it gallery. Find the main content block, remove any <txp:article.. /> tags, and replace it with something like this:

<div id="content">
<txp:image_index wraptag="div" break="" />
<txp:image_display />

You can use the standard wraptag, break and class attributes to control the layout.

2. Create a new section named gallery. Set Uses page to gallery.

3. Create one or more new image categories in textpattern > content > organise.

3. Upload some images via textpattern > content > images. Make sure each one has a thumbnail – you can use the create thumbnail feature – and assign it to one of your image categories.

4. View (or if you’re using Messy URLs). You can click on each image thumbnail to view the associated image.

There are several plugins that provide more complex gallery features.

Can I mix blog, static, and gallery pages?


Can a Textpattern site mix different kinds of pages? Static, weblog, image gallery, photoblog, portfolio, etc..


Yes. The usual way to do this is to use a separate section for each type of content – for example, a news section for your weblog-style content, a gallery or photoblog section for images, and a few sections named about, contact and so on for “static” content.

Each Textpattern section can have its own page template. Create one page template for each type of layout (weblog, image gallery, static), and assign the template to each section as appropriate. Then simply post articles and/or images in the appropriate sections.

See also How do I manage static pages? , How do I select which form is used to display articles?, and Can I use Textpattern for a photoblog?

Diagnosing performance problems

Normally, Textpattern is one of the fastest CMS platforms around.

However, there are a few circumstances that can cause performance issues. If you’re experiencing slow page loading, here are some things to check:

Runtime vs. Display Time

Textpattern records the time it takes to generate and send each page. You can check the “runtime” figure to distinguish between slowdowns during page generation, and those that occur afterwards (i.e. during page rendering).

In admin > preferences, set Production Status to Testing. Load a Textpattern page, view the HTML source, and scroll to the bottom. You should see a comment block that looks something like this:

<!-- Runtime: 0.1316 -->
<!-- Queries: 21 -->
<!-- Memory: 1988Kb -->

The figures will vary according to your server, page templates, and so on. On a properly configured web server with a normal load and typical Textpattern templates and content, expected ranges are as follows:

  • Runtime: 0.01 – 0.5 seconds
  • Queries: 20 – 50
  • Memory: 1500 – 3000 Kb

Please note that these are approximate ranges – a Runtime of 0.6 or 0.7 is on the high side, but not necessarily cause for alarm if your page templates are complex. Also bear in mind that the figures will be different for each page load, and will vary due to external factors like the traffic load on your web server. Try loading the page several times over a period of a few minutes and compare the results. A one-off anomaly probably means a temporarily overloaded server or network.

If you’re experiencing consistently high numbers, here are some things to check.


A runtime figure that regularly measures 1 second or more usually indicates one of two things:

  • DNS issues. A slow or misconfigured DNS server at your web hosting company can cause high page runtimes. Usually this occurs in the Textpattern logging code. In textpattern > admin > preferences > advanced, set Use DNS to No, and see if that makes a difference. If not, try disabling logging altogether.
  • Plugins. Plugins aren’t necessarily as efficient as Textpattern itself. If your performance problems coincide with the installation of a plugin, or occur only on a particular page template that invokes a plugin, try disabling it and see if there’s a difference. If your page won’t display properly without the plugin, try temporarily reverting to the default Textpattern page template and form .
  • PHP code. If you’ve included any PHP code in your page templates, whether directly in the template or indirectly via an include() call or similar, try disabling it. In particular, check for any code that might try to fetch a file from an external server, e.g. by using a http://.. URL in an fopen() or include() call.
  • MySQL issues. MySQL doesn’t have to run on the same physical machine as your web server. Some hosting companies run these on separate servers connected by a fast LAN connection, which is fine. However, if Textpattern and MySQL are on entirely different networks, performance will be unaviodably slow, since all MySQL queries and results must travel back and forth over a comparatively slow internet connection every time a Textpattern page is viewed.

Other MySQL performance problems can be harder to diagnose. An overloaded MySQL server can slow down Textpattern – ask your hosting company if this could be the case.

Queries and Memory

A high number of queries, or excessive memory usage, is usually caused by a plugin or custom PHP code. As above, try disabling this code to see if it makes a difference. Plugins that produce a list of articles are the most likely culprits: some popular “archive” plugins are very inefficient, loading the entire database of articles into memory at once. For an efficient method of displaying an archive list of articles, see here.

Page rendering

If your Runtime, Queries and Memory figures are all in or near the normal limits, but you’re still experiencing slow page loading, the problem is almost certainly caused by the content of your page. Some things to check:

  • Javascript – does your page include javascript code? Try disabling it, it might be slow.
  • Counters and external stats – are you using an image or javascript link to an offsite “hit counter”, stats service, or a local stats application like Shortstat? Try removing the link to see if it makes a difference.
  • Links to off-site objects – does your page link to images, javascript, CSS or other objects on another web server? Do your pages include content from external sources such as Gravatars, or similar? Any of these could be the culprit.
  • Advertisements – banner, popup and text ads all work by loading content from another server. Try disabling them and measure the difference.
  • CSS – certain CSS techniques can cause choppy page loading and scrolling. In particular, “fixed” background images and blocks can cause loading and scrolling problems. These problems are all on the browser side, and are unrelated to Textpattern or the server.

Improving performance

There are a number of articles around about improving Textpattern’s performance. Not all of this is good advice – many are outdated, some disable important features for no measurable benefit, and a few suggested techniques can acutally result in worse performance.

If your Runtime/Queries/Memory figures are within normal limits, but you’d like to improve performance, here are the best methods to use:

  • Minimize plugins. The more plugins are active, the more code must be loaded, parsed and run. Don’t use a plugin when you can achieve the same results with a built-in tag. And make sure you disable any plugins you no longer use.
  • Simplify your code. Do your templates use complex nested conditionals, PHP code, or forms within forms? Simplify them. In particular, try to reduce the number of <txp:...> tags that require database queries. (If you’re not sure, remove tags one at a time and watch the Queries count).
  • Caching. Sometimes pages are necessarily complex, and there are limits to server performance. If you have a popular site that’s not fast enough, try a caching plugin such as asy_jpcache or zem_cache.

The important thing with any performance tweak is to change only one thing at a time, and always measure the results. If something has no real effect, change it back and try something else. You’ll almost certainly find that one or two changes will have a large effect, while others will be insignificant.

How do I make an archive page?


How do I make an archive of articles grouped by month?
How do I show a list of all articles?


(This technique requires Textpattern 4.0.2+)

Here’s a step-by-step method for creating a page that lists all articles with headings for each month (or year):

1. Create a new article form (presentation > forms). Call it monthly_article:

<!-- show the year -->
<h2><txp:posted format="%Y" /></h2>
<!-- show the month -->
<h3><txp:posted format="%B" /></h3>
<!-- article title and link -->
<txp:permlink><txp:title /></txp:permlink>
<br />

2. Copy an existing page template (such as default) to a new one named archive_list.

3. Edit the archive_list template. In the main content block, replace the <txp:article /> tag with this:

<txp:article_custom limit=99999 form="monthly_article" />

4. Create a section named archive, list, or similar. The section page ( or will be used to display the list of articles. Select archive_list as the page template (“Uses page:”).


The monthly_article form above will display the year and month separately. You can combine them together like this:

<txp:if_different><h3><txp:posted format="%B %Y" /></h3></txp:if_different>

The format string can include any of the format specifiers supported by PHP’s strftime function. (Beware, Windows doesn’t support all of those). <txp:if_different> only displays its enclosed content when that content changes.

To include an excerpt, timestamp, category name or other information with each article link, simply use the appropriate article form tags in the monthly_article form.

To display the articles in an unordered list, use a li tag in the monthly_article form:

<txp:permlink><txp:title /></txp:title>

..and, in the archive_list page template, wrap the article_custom tag in a ul:

<ul><txp:article_custom limit=99999 form="monthly_article" /></ul>

To display only articles from a specific section or category, change the article_custom tag:

<txp:article_custom limit=99999 form="monthly_article" section="products" />


<txp:article_custom limit=99999 form="monthly_article" category="weather" />

To group articles by something other than date, such as section, create a form named section_article:

<!-- show the section -->
<h2><txp:section title=1 /></h2>
<!-- article title and link -->
<txp:permlink><txp:title /></txp:title>
<br />

And change the article_custom tag to sort by section:

<txp:article_custom limit=99999 form="section_article" sortby="section" />

Can Textpattern share a database?


Can Textpattern share a MySQL database with another application?
Can two separate Textpattern installs share the one database?


Yes. Set the Database Prefix to something unique when installing Textpattern.

For example, if you’re installing multiple Textpattern sites that share the one database, you might use txp1 as the Database Prefix for the first site, txp2 for the second, and so on.

Is there an article size limit?


What is the maximum size for a Textpattern article?
Is there a limit on comment size?


Textpattern uses a MySQL mediumtext field for article bodies. This limits the maximum size to about 16 megabytes per article—including any HTML tags that form part of the article body, but not counting images or files, since these are stored separately.

You’re more likely to run into a PHP memory limit than reach the article storage limit. Some hosts set the PHP memory limit to 8 megabytes.

The limit on comment size is 64 kilobytes.

Error: publish.php cannot be called directly


“If you just updated and expect to see your site here, please also update the files in your main installation directory. (Otherwise note that publish.php cannot be called directly.)”


This is most commonly caused by forgetting to update the topmost index.php file (or perhaps css.php) when upgrading.

Please ensure that you upload all files to your web server when you upgrade.

If you’re trying to include() publish.php from another script or page, please note that this is not recommended, and unsupported. Textpattern is intended to work as a stand-alone application. Embedding it in another script might break things in catastrophic or subtle ways, or (worse) open a security hole.

If you really must include publish.php from another script, start by examining the code in index.php.

Page output is unstyled


My page content and layout displays without any CSS styling


This is most commonly caused by an incorrect txpath setting in config.php.

View the HTML source of the page, and look for the <link rel="stylesheet" href="..." type="text/css" /> tag.

If the href link is incorrect—it should point to css.php?s=mysection or textpattern/css.php?s=mysection—you’ll need to edit config.php and fix the txpath setting. Check for an extra slash character, or repeated subdirectory name.

If the link appears correct, try pasting the CSS url directly into the address bar in your browser, and checking the output. Some possible diagnoses:

404 not found – your textpattern/css.php file is missing.

PHP error – if there’s a PHP error at the beginning of the CSS output, check the FAQ for more information.

HTML – if the CSS URL displays a HTML page instead of CSS code, you most likely have a missing css.php file, and/or an overzealous .htaccess RewriteRule. Try disabling .htaccess and switching to “messy” URL mode.

Blank page – switch the Production Status to Testing and reload.

If you just updated and expect to see your site here.. – if the CSS output includes this message, you haven’t updated the css.php file correctly when upgrading.

If you’re seeing some CSS styling, but not the style you’d expect, make sure you’ve applied the correct stylesheet to your section (textpattern > presentation > sections, “Uses style:”).

If you’ve manually created a <link rel="stylesheet" ... /> tag, rather than using the <txp:css /> tag in your template, make sure you’ve used the correct URL.

Help, I forgot my password!


How do I reset the administrator password?


A publisher can reset any user’s password. Provided there’s at least one publisher who can log in, ask them to reset your password for you.

If you’re the only user with publisher privileges (or the only Textpattern user at all), you’ll need to access the database directly to reset your password. Most web hosting accounts provide direct MySQL access using a program called phpMyAdmin, or via the command line. If you’re not sure how to access either of these, ask your hosting company’s tech support.

With phpMyAdmin, or at the MySQL command prompt, run the following query:

update txp_users set pass=password(lower('pass')) where name='user';

..where pass is the new password, and user is the login username.

Fatal error: Allowed memory size..


Fatal error: Allowed memory size of 8388608 bytes exhausted..


Textpattern’s memory usage is quite low – usually no more than a couple of megabytes.

Unless your server admin has set the PHP memory limit far too low — unlikely, but not impossible — the cause is probably a plugin. Some older archive page plugins work by loading all articles into memory at once. This could easily exhaust the available memory if you have a large number of articles.

Disable your plugins one by one, until you find the culprit. If the cause is indeed a plugin, we suggest contacting its author about the problem.

Alternatively, consider using the txp:article_custom tag to generate your archive list. <txp:article_custom /> uses memory efficiently. Some new tags in Textpattern 4.0.2 might help with formatting.

How should I ask for help on the forum?

The Textpattern Forum is for discussion and support of all things Textpattern.

Please bear in mind that it is a community forum – when you ask for assistance, you are asking volunteers and fellow users, not paid technical support staff.

The usual common-sense conventions of etiquette and politeness apply.

A few rules of thumb specific to the Textpattern forum:

  • Please make an effort to check the FAQ and documentation before posting, and check for duplicate threads on the forum. The forum search feature has been unreliable of late; try Google instead.
  • Try to choose the most appropriate forum for your question. Troubleshooting is for when you’ve tried something and it doesn’t work as expected. How do I? is self explanatory. Questions about plugins should go to the Plugins forum, not How do I or Troubleshooting.
  • If you’re asking for help with a problem or error, please describe the problem clearly and unambiguously. If there is an error message, please include an exact copy of the message in your post. If something doesn’t work as expected, describe what you’re expecting to see, and the actual behaviour. A link to the page in question is usually helpful, and sometimes a screenshot might be appropriate. Descriptions like “doesn’t work” or “it’s broken” are too vague, and unlikely to receive an answer.
  • Most suspected bugs aren’t really bugs, but problems caused by external factors. Unless you’ve confirmed the problem with a fresh install, or can identify the problem in the PHP source, start with a Troubleshooting post rather than a bug report.
  • Troubleshooting questions will usually be answered quicker if you include a copy of your diagnostics in your post (textpattern > admin > diagnostics). Don’t post the “High” detail version unless someone asks.
  • Questions about templates and appearance will usually benefit from including a minimal copy of the code in question. Edit out as much irrelevant code as you can—a short snippet of code is much easier for people to quickly diagnose than an entire page.
  • Surround HTML or template code with <code> </code> tags when posting.
  • Surround Textile code with <notextile> </notextile> tags when posting.
  • More detailed examples of how to post HTML, template and Textile code are provided in this FAQ
  • If you haven’t received an answer in a day or so, there’s probably a good reason: an ambiguous or rambling question, or not enough information. Don’t “bump” your thread with a single-word post, it’s more likely to annoy people than attract an answer. Post some more information instead.
  • Don’t post a troubleshooting question as a reply to an existing thread unless your problem is exactly the same as the one described at the beginning of the thread.
  • If you’re requesting a feature, this article lists some of the things you can do to increase its chances.

Does Textpattern support multiple weblogs?


Can I use one Textpattern install to manage multiple weblogs or sites?


You can achieve the appearance of multiple weblogs using sections – one section per weblog.

If you need complete independence between those weblogs or sites, or want to limit authors’ access rights to each weblog, you’ll have to use a separate Textpattern installation for each.

There are currently no plans to add multiple weblog support to Textpattern. We might add support for author access restrictions per section at some point, but there are no concrete plans on how that might work or when it might be available. Help is always welcome.

Is Textpattern search engine friendly?


Can I use Textpattern for SEO?


Yes. Textpattern employs many recommended usability and accessibility techniques, which are friendly to both users and search engines, right out of the box.

The default page template is clean, minimal xhtml, with CSS stylesheets linked externally. Textile automatically generates valid XHTML for page content.

Textpattern supports “clean” URLs on most systems (like the URL of this page, -textpattern-search-engine-friendly). Each article URL is unique, to avoid problems with duplicate content, and the URL title and page title can be set independently. Though pages are generated dynamically, from a spider’s point of view they are generally indistinguishable from static HTML.

Missing or deleted pages are handled correctly with a 404 response. There are no session IDs or cookie checks to interfere with seach engine spiders. The /section/id/title URL structure makes it easy to exclude specific sections with robots.txt.

Meta keywords can be set per-article, and page titles are unique. There is a built-in txp:breadcrumb tag. A site map is easy to create with the txp:article_custom tag.

Textpattern’s basic organisation tends to suit a flat, broad site structure, which is generally regarded as search-engine-friendly, rather than deep nesting, which can be harder for both users and spiders to navigate.

More advanced techniques can be implemented using custom fields and plugins.

Is there a tag or attribute for..


Is there a tag that does xyz?
What attributes are supported by which tags?


The documentation at Textpattern Documentation is detailed and helpful. Even experienced users will probably learn something they didn’t already know.

The Textpattern Tag Reference describes almost every tag, organised by function. (It also includes an alphabetical tag list.)

Brand new tags and attributes might not be listed. Textpattern Documentation is a community effort, so if you find something missing, consider submitting some documentation yourself

How do I change the appearance of..


How do I change the appearance of a particular tag?
How do I change the markup used by a particular tag?


Most tags that display content with markup support some (though not necessarily all) of the following attributes:

  • wraptag – a tag that wraps around content; typically ul by default
  • classCSS class applied to the wraptag; typically uses the tag name by default
  • break – a tag used to wrap or separate each item in a list (of articles, links, etc); typically li by default
  • breakclassCSS class applied to each break tag

It’s not necessary to include < and > in these attributes. If you use the tag names only, Textpattern will handle common self-closing tags correctly. For example:

<txp:section_list wraptag="div" break="br" />

produces something like this, with <br /> tags following each item:

<div class="section_list">
<a href="/section1/">section1</a><br />
<a href="/section2/">section2</a><br />

While this:

<txp:section_list wraptag="ol" break="li" />

produces <li> tags that surround each item:

<ol class="section_list">
<li><a href="/section1/">section1</a></li>
<li><a href="/section2/">section2</a></li>

A detailed list of tags and their supported attributes can be found in the Textpattern Tag Reference. The Attribute Cross Reference lists the tags that support each attribute.

Comment emails aren't received


Comment and/or password emails are never received
Can Textpattern send mail from Windows servers?


Textpattern uses PHP’s built-in mail functions to send email. Email should work on any properly configured system. Unfortunately, not all web hosts configure PHP’s mail settings correctly – particularly on Windows servers.

Additionally, some servers perform spam filtering on outgoing email, or block messages that don’t have a recognized From: address.

Ask your web host’s technical support about PHP mail to find out if it’s properly configured, and whether there are any restrictions. Textpattern uses the Publisher user’s email address as the From: address when sending password emails, and the article author’s email address when sending comment notifications.

If you’re running Textpattern on your own server, please check your email settings in php.ini.

On Windows servers, or Unix servers that block or restrict access to sendmail, you’ll need to set STMP and smtp_port.

Can Textpattern import entries from..


How do I import data from my old weblog or CMS?
What import formats does Textpattern support?


Textpattern has a built-in import function that supports the following applications and formats:

  • b2
  • Blogger
  • Movable Type
  • WordPress

In addition, Textpattern can import from any application that supports the Movable Type Import Format.

If you need to import data from an application that isn’t supported here, your options are:

  • Write a script or template to export your data using the MT Import Format.

This is how the Blogger import works: you create a template that displays articles in the MT format, and save the output as your export file.

  • Write your own import script for Textpattern.

The easiest way to do this is to copy one of the existing scripts and modify it to suit. The scripts are located in textpattern/include/import/. If you’re importing directly from a MySQL database, the simplest script to start with is import_b2.php.

The install page shows a jumble of PHP code


When I view Textpattern pages, all I see is the contents of the PHP files


Either one of two things is happening:

1. Your server isn’t configured to interpret .php files as programs.

Ask your web host or server admin to set up the necessary AddType magic. If you’re running your own server, please see the PHP Installation instructions.

2. You’re trying to open Textpattern’s PHP files directly from your own computer, perhaps using a file:.. URL.

If you want to run a Textpattern installation on your local machine for test purposes, and have all the necessary server software installed, make sure you access Textpattern via http://.. URLs. If you use file:.. URL instead, your web browser will open the PHP files directly, bypassing the web server and PHP software.

How are sections and categories different?

Sections are exclusive. Every article is associated with a section. An article cannot reside in more than one section.

A newspaper web site might have sections named “Politics”, “Sport”, “Weather” and so on.

Categories are a looser way of organising articles. An article can have up to two categories, and may have none. Categories may cross Section boundaries – that is to say, articles from several different sections can belong to the one category.

Following the newspaper example, categories might be used to organize articles into “Local”, “National”, “World” and so on.

Categories can be used independently (to list articles from all sections in the National category, for example), or combined with sections (to list articles in section Politics with category World).

For a more detailed explanation of how Textpattern organises content, read I’ve installed Textpattern. Now what?

How do I use custom fields?


Can I attach additional information to articles?


Textpattern’s custom field feature allows you to attach extra information to articles: prices, URLs, phone numbers, or whatever suits your application. It’s not a substitute for a full-fledged, custom-designed database, but works well for simple designs.

Each article can have up to 10 custom fields. Each custom field can contain a simple string, limited to 255 characters.

Let’s say we want our Textpattern articles to have an extra field, representing a manufacturer name.

First, we need to set the field name. Under textpattern > admin > preferences > advanced, set Custom field 1 name to manufacturer, and save the settings. It’s a good idea to use a name that is lowercase and contains no spaces.

Next, we need to add a tag to display the contents of the field. In your article form, add something like this:

<p>Manufacturer: <txp:custom_field name="manufacturer" /></p>

Finally, add the manufacturer name to each article. Under textpattern > content > write, click Advanced Options, and you should see a text input box with the title manufacturer. Add the manufacturer name there, and it will be displayed by the <txp:custom_field .. /> tag.

Custom field names are global, but you don’t have to use them on every article. To display custom fields only for a particular section, either use a different page template and article form for that section; or wrap an if_section conditional around the <txp:custom_field .. /> tag.

The txp:if_custom_field tag may also prove useful. It checks the value of a custom field. For example, to hide the “Manufacturer:” text on articles that have no manufacturer name:

<txp:if_custom_field name="manufacturer">
<p>Manufacturer: <txp:custom_field name="manufacturer" /></p>

You can also use custom fields to store URLs. For example, if we added a second field, manufacturer_url:

<txp:if_custom_field name="manufacturer_url">
<p>Manufacturer: <a href="<txp:custom_field name="manufacturer_url" />"><txp:custom_field name="manufacturer" /></a></p>

For more information, read txp:custom_field.

Can I use Textpattern for a photoblog?

Sure. Textpattern has an Article image feature, which lets you attach a photo to each article.

All you need to do is use an article form that includes the <txp:article_image /> tag. Each time you want to post a new image, create a new article with the image attached.

You can manage the images themselves using Textpattern’s image upload feature, or upload them yourself using FTP if you’d prefer.

For more detailed instructions, read Creating a photoblog with Textpattern.

Article Images aren't working

To use Textpattern’s Article image feature (under Advanced Options on the content > write page), you need to do two things:

1. Place an image URL or ID in the Article image field. The ID is a single number, like 123 – don’t use an extension. If you want to refer to it by filename, you’ll need to use an absolute URL like /images/cat_pic.jpg or Don’t put HTML or Textpattern tags in the Article image field, they’re not needed and won’t work.

2. Make sure your article form includes the following tag:

<txp:article_image />

More detailed instructions are included in Textbook.

How do I search in the current section only

You can easily display search results for a given section only. All you need to do is to add a couple of custom attributes to the <txp:search_input /> and <txp:article /> tags on the template page for that section.

  1. First, you need to point the search input to the current section page, by adding to the <txp:search_input /> the attribute section with the current section name as the value.
  2. Then, in order to display the search results only for that section, you have to add searchall=”0” as attribute for the <txp:article /> tag on that page.

How do I back up Textpattern?


Does Textpattern have a built-in backup function?
How do I move Textpattern from one server to another?


Currently, there is no built-in backup or export function in Textpattern. You can use several tools designed for the purpose:

phpMyAdmin is supplied by most web hosts. The phpMyAdmin FAQ has a brief explanation of how to back up and restore.

mysqldump generates SQL backups that can be restored using phpMyAdmin or with the mysql command-line client. See the MySQL manual for details.

rss_admin_db_manager is a Textpattern plugin that includes backup and restore functions. Read more here.

If your server runs Unix, and has a cron function, here’s a sample crontab entry for an automatic weekly backup:

0 0 * * 0 mysqldump -Qc -u mydbusername --password=mydbpassword mydbname | gzip > $HOME/txp_backup-`date '+%Y%m%d'`.sql.gz

If you don’t know what a crontab is, or how to test one, we recommend instead using one of the other options listed above.

AutoMySQLBackup is an open source Unix shell script which automates the process of rotating daily, weekly, and monthly MySQL backups.

The remark regarding crontabs applies here as well.

Tabs show up as tab_content, tab_presentation..


All of the text on my admin pages shows up as short phrases with underscores (tab_content, advanced_options, etc)


This happens when there is no language installed. (Perhaps you encountered an error during the setup process?)

Go to tab_admin > tab_preferences, manage_languages, then install or update the appropriate language.

If the language is installed correctly and the problem persists, try switching to a different language and back.

404 error unless I use index.php

QUESTION: works, but gives a ‘404 Not Found’ error


Uncomment (remove the ”#” from) the following line in your .htaccess file:

#DirectoryIndex index.php index.html

If that doesn’t help, or causes a 500 Internal Server error, contact your web host tech support and ask them about enabling DirectoryIndex for PHP files.

How do I fetch the current development version?


How do I fetch the latest copy of Textpattern from Github?
Which branch or release should I use?
Where can I get old versions of Textpattern?


The Textpattern source code is stored in a git repository at Github. The important endpoints are:

releases – contains a copy of most official Textpattern releases, identical to the .zip/.tar.gz downloads. This is mostly useful if you’re looking for an older version.

master – the main 4.x branch. This is where we work towards each new release (4.5.0, 4.6.0 etc). Please note that, while the 4.x branch is intended to be stable and reliable, the changes between releases occasionally include errors or omissions. If you’re looking for the most reliable current copy of Textpattern, use the latest release.

To download from Github, you’ll need to install the git command-line client (for most operating systems, including OS X). There are graphical clients available, such as Github for Windows or OSX should you prefer, although the command-line version gives far more flexibility.

The command you need to get started is:

$ git clone

That will clone the repository to your machine, you can use git config to set up a few things like your and, then you’re free to make changes, publish them to your own github repo and issue a Pull Request for us to merge your changes, or just create a diff patch and send it to us.

Note there are experimental branches that contain new features in development that are not ready to merge into the master branch yet. Feel free to peruse these using:

$ git checkout name-of-branch

You can see the list of available branches using the git branch command. To get back to your master copy, use git checkout master.

Stop feeds updating on comments?


How do I stop XML feeds from registering an update when a comment is posted?


There are two configuration options for this. In preferences > advanced, under the Publish heading:

  • Show comment count in feeds? no/yes

This determines whether or not the comment count is included in the article title in XML feeds (‘My article [4]’).

  • New comment means site updated? no/yes

This controls whether or not to signal a feed update when a comment is posted.

Where can I get the default templates?


How do I restore the default templates, forms, and styles that came with Textpattern?
I messed up my default template/form, how do I fix it?


The default templates, forms and styles that come with Textpattern are all listed in Textbook:

You can save or restore them into your Textpattern site by pasting the contents of each into the edit interface – presentation > templates, presentation > forms, or presentation > styles.

Client does not support authentication protocol requested by server


Warning: mysql_connect(): Client does not support authentication protocol requested by server; consider upgrading MySQL client in /Library/WebServer/Documents/tp1/textpattern/setup/index.php on line 187


This and similar errors are caused by a PHP installation problem: the version of the PHP mysql client library is older than the MySQL server.

You should raise a support ticket with your web hosting company, and ask them to reinstall the correct versions.

Comment display confusion


Why does the comment for show up twice?
How do I change the comment display markup?
What are all these comment forms for?


Earlier versions of Textpattern were inflexible in the way comments were displayed. The list of comments, and comment input form, were always appended to the end of an article on an individual article page. This made it impossible to shift the comments to a different part of the layout (like a separate column), or display them on list pages.

Since RC5, there are some new comment tags that provide greater flexibility.

The default behaviour is to mimic older versions, by automatically appending comments and the comment input form to articles. You can disable this behaviour by turning off the Automatically append comments to articles? option on textpattern > admin > prefs.

If you disable that setting, you’ll need to manually include the necessary comment tags in your article form, or comments won’t be displayed at all. (Conversely, if you use these comments tags without disabling the Automatically append comments to articles? setting, you’ll see comments displayed twice).

The important tags are:

  • txp:comments – displays the list of comments. By default, this uses the form named “comments” to display each comment.
  • txp:comments_form – displays the comment input form. By default, the input form markup is stored in the form named “comment_form”.
  • txp:if_comments_allowed – checks if comments are permitted for the current article

The default forms are:

  • comments – this is used by the <txp:comments /> tag to display each comment in the list
  • comment_form – this is the comment input form, as displayed by <txp:comments_form />
  • comments_display – this contains the code to display the comment input form, preview, and list of comments for an article.

You’ll find a minimal set of comment tags in the default comments_display form.

If Automatically append comments to articles? is turned on, this form is used automatically each time an article is displayed.

If you’ve turned off Automatically append comments to articles?, append this code (or something like it) to your article form as a starting point.

Where are the installation instructions?

The installation instructions on the download page are brief but accurate.

There are some step-by-step instructions at Textbook.

Make sure you have the following before trying to install Textpattern:

  1. The name of a MySQL database.
  2. A username and password that is sufficient to access the database.
  3. The hostname for your MySQL server. This is almost always localhost.

How do I create navigation links?


How do I link to sections?
How do I link to categories?
How do I link to static pages?
How do I make a menu of section links?


Sections are usually the topmost navigation elements of your web site (more on site structure here). If you want a simple, automatic list of links to sections, use the section_list tag:

<txp:section_list wraptag="ul" break="li" />

This puts the links in an unordered list, so you can use CSS to alter the layout as required (see A List Apart for some examples).

For a popup selection list, use the popup tag:

<txp:popup type="s" />

If you want more control over the content of the list (to omit certain sections, or use a specific order), the best way is with the <txp:section /> tag (requires Textpattern 4.0.2+):

<txp:section wraptag="li" link=1 title=1 name="about" />
<txp:section wraptag="li" link=1 title=1 name="articles" />
<txp:section wraptag="li" link=1 title=1 name="news" />
<txp:section wraptag="li" link=1 title=1 name="contact" />

If you’ve created static pages, like an about or contact page, you can link to them by linking to the associated section:

<txp:section link=1 title=1 name="about" />
<txp:section link=1 title=1 name="contact" />

Category links are specified in a similar way. There’s a category_list tag:

<txp:category_list wraptag="ul" break="li" />

The popup tag can also be used for categories:

<txp:popup type="c" />

Please note however that categories are independent of sections. Both of these tags will link to a list of articles in all sections that belong to the selected category.

For more control, you can use the category tag (also requires Textpattern 4.0.2+):

<txp:category wraptag="li" link=1 title=1 name="products" />
<txp:category wraptag="li" link=1 title=1 name="weather" />
<txp:category wraptag="li" link=1 title=1 name="photos" />

When will the next version be released?


When is the next version due out?
When will feature X be added to Textpattern?


We don’t discuss release dates or speculate about upcoming features in advance, because such predictions are invariably incorrect.

Textpattern is an open source project. It is not developed in the same way as a monolithic, proprietary application. We don’t have a battery of programmers paid to obey orders. Textpattern’s developers – the core team, and occasional contributors – contribute code that they’ve written for their own projects and personal use.

This is not a bad thing: it means that the features added to Textpattern have been developed based on needs, not conjecture; and have usually already been tested on live sites.

What does this mean for your pet feature wishlist? The priority of the development team will always be with the things that are closest to completion. The more you can bring to the table, the more attention we’ll give in return.

You don’t have to be a software developer to help create a new feature: documentation, examples, test cases, and use cases will all help.

412 Precondition Failed


Why do I get a “412 Precondition Failed” error when submitting a form?
“mod_security: Access denied with code …”
I get a mysterious server error when trying to save a page template or form.


These and similar errors are usually caused by mod_security filtering. Some hosting companies use mod_security or other similar filters to block web form submissions containing certain key words or suspicious symbols, in order to prevent comment spam or hack attempts. Occasionally these security rules can block legitimate requests.

Textpattern never sends a 412 response.

You should raise a technical support ticket with your hosting company. There is nothing Textpattern can do to fix the problem.

What does article_custom do?


What’s the difference between <txp:article /> and <txp:article_custom />?
I used <txp:article_custom />, and now something isn’t working!


The <txp:article /> tag is context sensitive. The article(s) it displays depends on the URL of the current page. The results will change if the URL includes a section, for example, or a category, or a search query, an article ID, or a page number parameter. It’s normally used to display the main content of a page.

The <txp:article_custom /> tag ignores the page URL. The article(s) it displays depends only on the tag attributes. The results won’t change on a search result page, when navigating by category, section or article, or when paging. It’s typically used to display a list of articles in a sidebar.

See also Why aren’t the right articles showing up on my page?

How do I keep a post at the top of the page?


How do I create an article that isn’t included in the regular article list?
How do I create an article that’s only displayed on the front page, and nowhere else?


This is what Sticky articles are for.

The Sticky status means an article has been published, but is not included in the regular list of articles. It’s displayed only when requested with the status="sticky" attribute. For example:

<txp:article status="sticky" limit=1 />
<txp:article limit=10 />

..will display the most recent Sticky article, followed by the 10 most recent Live articles. On a section page, both tags will select articles from the current section only. On the front page, these tags will select articles from sections that have On front page? set to Yes.

To display a specific Sticky article, rather than the most recent, use the following tag:

<txp:article_custom status="sticky" id="123" />

..where 123 is the ID number of the article you want to show. You can use this to show a sticky article in a section other than the one it belongs to, or to pin a specific article to the front page of your site. The article_custom tag ignores the URL, so the selected section has no effect.

A commonly requested variation is to display an introduction on a section page (or the front page), with headlines or manually crafted links to individual article pages. For that, you can combine Sticky articles with the conditional tag method outlined in this faq:

<!-- section page: display the sticky article -->
<txp:article status="sticky" limit=1 />
<txp:else />
<!-- article page: display the live article -->
<txp:article limit=1 />

How do I change the article markup?


How do I get rid of <p> or <br> tags in article bodies?
How do I get more control over HTML markup in article bodies?
Why are my excerpts enclosed in <p> tags?
How do I turn off Textile?


By default, Textpattern articles are written in Textile, the Humane Web Text Generator. Some quick examples of Textile in action:

*bold* becomes bold
_emphasis_ becomes emphasis
"link": becomes link

You can read more about Textile here, and try it out for yourself.

As well as explicit markup such as the examples above, Textile automatically wraps blocks of text with <p>...</p> tags, and turns line breaks into <br /> tags.

If this is inconvenient, you can turn Textile off individually for a single article with the Use Textile setting under Advanced Options, just to the left of the main article text on the content > write page. There are separate settings for the body and excerpt.

To turn off Textile by default, look for the Use Textile setting under admin > preferences.

Both options require that you resave your article before they have any effect.

If you just want to disable Textile for part of an article, you can use several methods:

1. A space at the beginning of a line will turn off <p>...</p> tags for that line

2. To disable Textile for a few words, use ==...==

3. To disable Textile for a larger block, use <notextile>...</notextile>

If you’re writing an article body or excerpt that consists mainly of hard-coded HTML or Textpattern tags, or where you need exact control over the markup, your best bet is to turn off Textile for that article, and hand-code the markup yourself.

How do I skip the comment preview?


How do I get rid of the comment preview, and make it a one-step submit?


You don’t. The preview step is an important part of Textpattern’s anti-spam mechanism. And trust me, you need that. The only reports we’ve received of automated comment spam against Textpattern is on sites where the preview mechanism has been disabled.

There are some instructions floating around that describe ways of disabling it. Usually these are for older versions of Textpattern, and often the result is that comments stop working, or something else fails.

How fast is Textpattern?


Do I need to install a caching solution for my Textpattern site?
How do I improve Textpattern’s performance?


To the best of our knowledge, Textpattern is at least as fast as any similar weblog/cms package, and often several times faster. Out of the box, and running on modest server hardware, it can comfortably handle several page views per second (i.e. hundreds of thousands of hits per day).

Sencer posted some benchmarks that demonstrate a default Textpattern install is around 2-3 times faster than Wordpress.

Caching is normally of benefit only for web sites with very heavy traffic – in the order of many requests per second. You’ll find some information about caching here, including comparisons to other cached weblog packages.

On a fast server, Textpattern can serve dozens of hits per second without caching, and hundreds per second with caching installed [1].

Though there are several articles floating around that describe some methods of optimizing Textpattern’s performance, most of these were written for older versions of Textpattern. Our experience is that most of these optimizations make no significant difference in real-world tests, and some actually degrade performance.

If you’re experiencing performance issues due to sudden heavy traffic (such as a slashdotting), you can temporarily reduce the server load by setting “Logging” to “None” (textpattern > admin > prefs). Under normal circumstances, this has no significant performance benefit.

[1]. Source: TextDrive weblog, Sencer’s caching plugin for textpattern is snazzy.

How many articles can Textpattern handle?


Can Textpattern run a site with thousands of articles?
How many articles can Textpattern handle before it becomes too slow?
Is there any limit on the number of articles or pages?


There is no limit on the number of articles Textpattern can cope with. Many sites use Textpattern to manage thousands of articles without any problems.

Performance is not dependent on the number of articles. Textpattern is very fast, and there is normally no noticable difference in speed between a site with a dozen articles, and one (on the same server) with thousands of articles.

Textpattern does not have a “rebuild” process, so posting or editing an article is just as fast for your 10,000th article as for the first one.

I've installed Textpattern. Now what?


I’m confused about how Textpattern organizes things
Sections, pages, forms – please explain!


Textpattern is a blank slate. Though it almost always works out-of-the-box, and includes a simple layout and structure to get you started, you’ll need to learn some basic concepts in order to shape it to your needs.

Briefly, the important concepts in Textpattern are:


Sections are the topmost divisions of your web site. A newspaper site might have sections like “Politics”, “Sport”, “Weather”, and so on. These usually correspond to URLs such as,, etc.

Sections are managed in the Textpattern administration panel under presentation > sections.

Each section contains any number of articles. Sections can look the same, or each one can have a unique page layout.

A section page – like – will typically display a list of recent articles in that section, much like a weblog. It doesn’t have to be a weblog, however: it might display a single article (as in a ‘static’ page like an About page), or a list of articles organized in some other fashion (as in this FAQ section).


Articles are where you store your content. Each article has a title, excerpt, body, and can contain user-submitted comments.

Each article belongs to one section (and only one).

Every article has its own unique page and URL, usually called an individual article page or permlink page. URL modes are configurable, but it often looks like

To write a new article, go to content > write in the Textpattern administration panel. To edit or remove existing articles, go to content > articles.

Page Templates

Page templates determine the HTML code used to display list and individual article pages. Each section has an associated page template that’s used when displaying lists or articles in that section. You can share the same page template between multiple sections, or create a unique one for each section if you wish.

Page templates contain textpattern tags, which are used to insert dynamic content into the page. For example, the <txp:article /> tag will display the article(s) associated with the current URL.

Page templates are managed in the presentation > pages tab of the administration interface. To assign a template to a particular section, go to presentation > sections.


Forms are short snippets of HTML used to display repeated content. Each form has a type: article, link, misc, etc.

An article form is used by the <txp:article /> tag to determine how to display each article on the page, for example.

Like page templates, forms can contain Textpattern tags. The article form will typically include the <txp:title /> and <txp:body /> tags, for example, which display the article’s title and body respectively.

You can use misc forms for snippets of HTML code you use on each page, such as a header or footer. (read how)

Forms are managed in the presentation > forms administration tab.


Styles are CSS stylesheets. Like page templates, each section has an associated style. You can use a unique style for each section, or share one between many sections.

Styles are managed in the presentation > style tab. To assign a style to a section, go to presentation > sections.

The Front Page

The front page of your Textpattern site – typically – works as a container for all sections. The front page has its own page template and style setting; just like sections, it can have a unique page template and style, or share them with other sections.

You can’t assign articles directly to the front page. Instead, each section has a setting (“On front page?”) that determines whether or not the articles in that section should be displayed on the front page.

Images and Files

Textpattern has a built in administration interface for uploading and managing images and files.

The content > images tab is used to upload and manage images that are displayed as content in a page, as elements in a layout, in an image gallery, or within an article body. Several built-in Textpattern tags are available for using images in a page template or form: <txp:image />, <txp:article_image />, etc.

The content > files tab is used to upload and manage files that are made available for users to download. A number of file_download template tags are available for creating file download lists.

Alternatively, you can upload and manage images or files manually using FTP and similar programs. You’ll have to use hard-coded HTML and URLs to reference these files, however. (Be careful when using relative URLs).

Images are broken on certain pages


My images show up broken on category pages
My images show up broken on article pages
Stylesheets are broken on article pages


Images or CSS stylessheets that are broken only on certain pages using clean URL mode usually indicates a problem with relative URLs.

Clean URLs look something like this:

When you use a relative image URL – such as <img src="images/foo.jpg" />, or (in Textile) !images/foo.jpg! – it’s the web browser that appends that image URL to the current page URL to resolve the final location, not Textpattern. When viewing the pages listed above, the web browser would request images from these URLs:

The first of these might work, but the second and third won’t.

The same applies to stylesheets, and to images referenced within stylesheets.

There are several solutions.

One is to always use absolute URLs for images and stylesheets. Instead of images/foo.jpg, use /images/foo.jpg. (If Textpattern is installed in a subdirectory, use /mysubdir/images/foo.jpg instead).

Another is to specify a base URL in your page template, like this:

<title><txp:page_title /></title>
<base href="">

That instructs the web browser to use as the base page when resolving all relative URLs.

When linking to images, you can use two tags to help.

The txp:image tag lets you display any image that was uploaded using Textpattern’s image manager. You refer to the image by its ID number:

<txp:image id="3" />

..or by name (minus the file extension):

<txp:image name="foo" />

To link to other images, you can use the txp:img tag, which prepends the Textpattern root URL to image paths:

<txp:img src="images/foo.jpg" />

For other types of links, the txp:site_url tag will be useful.

More information at, HTML and URLs.

How do I change the number of articles displayed?


How do I change the number of articles displayed in a list?
How do I tell Textpattern to display only 1 (or 10, or 100) articles per page?


Edit your page template, and change the <txp:article /> tag to include a limit attribute, like this:

<txp:article limit=1 />

or this:

<txp:article limit=10 />

If no limit is specified, the default is 5.

To link to the next and previous pages from a list page (i.e. on your front page, or a section page), use the txp:older and txp:newer tags.

To link to the next and previous article from an article page, use the txp:link_to_next and txp:link_to_prev tags.

You can do this with one chunk of code in your page template, as used in Textpattern’s default template:

<txp:link_to_prev><txp:prev_title /></txp:link_to_prev>
<txp:link_to_next><txp:next_title /></txp:link_to_next>

Blank page after editing a page template


I changed a tag in my page template (or form), now the page is completely blank!
A large portion of my page is missing


This usually means an error has occured but is not displayed because you’re running in Live mode. Setting the Production Status preference to Live suppresses all error messages. When a fatal error occurs in Live mode, the result is a blank page.

Go to textpattern > admin > preferences, and set Production Status to Testing, then view the problem page again. You should see a more informative error message this time.

It’s always a good idea to use Testing mode when editing templates and forms. Switch to Live mode only when you’re certain everything works.

(Debugging mode is intended only for developers; it’s normal to see some spurious messages in this mode)

If you’re still seeing a blank page even in Testing mode, the most likely cause is a syntax error in one of your <txp:...> tags. Common problems to look for include:

  • unclosed tags
  • <txp:else> instead of <txp:else />
  • </txp:foo /> instead of </txp:foo>
  • <txp:foo instead of <txp:foo>

Parse error: unexpected ..


Parse error: parse error, unexpected ’.’ in /home/domain/www/txp/textpattern/lib/txplib_forms.php on line 167
Parse error: parse error, unexpected ..


These and similar errors occur when Textpattern’s PHP files have been corrupted or incorrectly modified. The best solution is to download a fresh copy and replace the files on your server.

If you’re experiencing repeated problems, make sure your FTP client (or whatever program you’re using to transfer files to your server) isn’t set to ASCII mode.

Warning: Missing argument 2 for..


Warning: Missing argument 2 for if_comments_allowed() in /httpdocs/textpattern/publish/taghandlers.php on line 1188
Warning: Missing argument 2 for some_function ..


These and similar errors occur when an enclosing <txp:...> tag isn’t closed properly. The function name will be the name of the tag (<txp:if_comments_allowed> in the above example).

Check for errors like these in your page templates:

Using an enclosing tag as self-closing

<txp:some_tag /> instead of
<txp:some_tag> ... </txp:some_tag>

Error in closing tag

</txp:smoe_tag>, or

</txp_some_tag>, or


Missing closing tag


How do I log in?


Where is the Textpattern administration panel?
I’ve forgotten where the login page is!


If you’ve installed Textpattern at the root of your web site, go to

If Textpattern is installed in a subdirectory, try

On most servers you can leave off the index.php part.

Textpattern crashes Apache under WAMP

A known bug in either PHP or Apache causes the Apache process to crash during Textpattern setup on certain versions of WAMP (PHP 5, Apache/1.3.33).

The bug is triggered by the apache_get_modules() function call.

There are no plans to alter Textpattern to work around the problem, since the bug is in the web server itself. We think it’s reasonable to include “a web server that doesn’t crash” in the list of Textpattern system requirements.

See also this forum thread and weblog post.

Clean URLs don't work


Permlinks don’t work
I get a 404 error when trying to comment
I get a 404 error when trying to view article pages
I get a 404 error when trying to view section pages
The wrong content is displayed in clean URL mode


These and similar problems happen when you use “clean” URL mode on a server that doesn’t support mod_rewrite in .htaccess, or requires additional configuration in order to work. The .htaccess file supplied with Textpattern is designed to work on most Apache servers, but there is no universal solution.

The Textpattern diagnostic page will attempt to warn you if it can determine that clean URLs are not supported on your system. However, it doesn’t detect all incompatible servers – the absence of a warning does not mean that your server supports clean URLs.

The simplest solution is to use “messy” URLs instead (see textpattern > admin > preferences > permanent link mode, and remove or move aside the .htaccess file).

Some servers support mod_rewrite, but require some additional configuration in order to make it work properly.

If your web server is Apache, and supports mod_rewrite in .htaccess, you can find some suggestions for specific web hosts in this forum thread. “1and1” is the most common host that requires such changes for clean URLs to work.

Hosts that support Textpattern clean URLs out of the box include TextDrive, DreamHost and BlueHost.

Most free or nearly free hosting services don’t support clean URLs at all. In some cases clean URLs appear to work fine at first glance, but might fail in subtle ways.

On servers that support mod_rewrite, the most common solution is to uncomment (remove the leading ‘#’ from) this line in .htaccess:

#RewriteBase /relative/web/path/

..and change the path as appropriate. If Textpattern is installed in your web site root (i.e. the front Textpattern page is at, you should use this:

RewriteBase /

If Textpattern is installed in a subdirectory (the front Textpattern page is at

RewriteBase /mydir/

Other changes required on some hosts include:

DirectoryIndex index.php index.html


Options +FollowSymLinks

Both of these lines are included in the default .htaccess file, so you can simply uncomment them.

If you are configuring your own Apache server, or using a hosting arrangement that lets you modify your own Apache configuration settings, you might need to add the following to the appropriate place in httpd.conf:

AllowOverride FileInfo

If none of those changes work, or if they cause a 500 server error, you’ll need to use “messy” URLs instead, or ask your hosting company for help.

How do I embed Textpattern in another page?


How do I embed Textpattern in another page or script?
I tried include()ing publish.php and it didn’t work!


Textpattern is designed as a stand-alone application. Trying to embed it in another page or script doesn’t work well, for various reasons. (In particular, Textpattern uses output buffering, If-Modified-Since caching, and sends HTTP headers, all of which usually interfere with wrapper scripts)

Usually that turns out not to be nessary though. Try doing things the other way around: embed your content or script in Textpattern, using page templates, forms and < txp:php> tags. That way you’ll have a consistent interface for editing all of your pages.

Can I use Textpattern to do this?


Can I use Textpattern to build a web site like..


Textpattern is endlessly customizable and extendable via templates and plugins. It’s also open source, so you can modify the code as required. So the short answer to that question is: yes, you can build pretty much any kind of site you like with Textpattern, if you’re willing to do the work.

You’ll find many examples of Textpattern-powered sites listed in the Let’s See Yours, Then forum.

TXP Magazine’s txp sites gallery and sites collection by category list some well-designed web sites that use Textpattern.

If you break your requirements down into specific features and questions, you’ll find most of the answers in the Textbook documentation and this FAQ.

If what you really mean is, will someone please tell me how to do this, or can I just click a button and have my site look like this, or perhaps can I do this in the eight hours left before my deadline, we’ll leave you to work out the answers to those questions.

500 Internal Server Error


I get a “500 Internal Server Error” when trying to view pages
I get a “403 Forbidden” when trying to view pages


These and similar errors are almost always caused by .htaccess.

The .htaccess file is used by Textpattern to mange “clean” URLs – instead of

While we’ve done our best to ensure the .htaccess file supplied with Textpattern will work with as many web server configurations as possible, some servers are configured to restrict this. A 500 Internal Server Error or 403 Forbidden response is usually the result of a .htaccess file that tries to exceed these restrictions.

The simplest thing you can do to fix the problem is simply delete or rename .htaccess, and switch to “Messy” URL mode (see textpattern > admin > preferences > permanent link mode).

You’ll find some other pointers in this FAQ.

Where can I download .htacccess?


My .htaccess file is missing. Where can I get a copy?
.htaccess isn’t in the download!


The .htaccess file is inside the main directory in both the .zip and .tar.gz downloads. Some file browsers (particularly on OS X) don’t display files beginning with a ‘.’ by default, but it’s there, honest.

You can also fetch it from the subversion repository.

If you’re planning on using clean URLs, you’ll need to make sure you upload this file to your web site. The safest way to do this is usually to upload the ‘textpattern-4.0.7’ folder to your server, then moving it to the correct place, rather than selecting and uploading the contents of the ‘textpattern-4.0.7’ folder.

Some servers require manual changes to .htaccess for Clean URLs to work, and others don’t support it at all. You’ll find more information in this FAQ.

Which articles go on the front page?


How do I control which articles are shown on the front page?
How to I make the front page show articles from particular sections?
How do I stop articles from some sections from showing up on the front page?


Each section has a setting that controls whether or not its articles will be shown on the front page by default.

Go to textpattern > presentation > sections, and select On front page? appropriately for each section.

Notice: undefined variable..

When your Production Status is set to Debugging, it’s not uncommon to see PHP Notices similar to this:

Notice: Undefined index: permlink in …/textpattern/lib/txplib_misc.php(412) : eval()’d code on line 26

Debugging mode is intended for just that: debugging problems. If everything is working fine, there’s no reason to turn on Debugging.

Notices in debug mode are not unusual, and by themselves aren’t an indicator of something wrong. If the only symptom you have is that there are notices produced when Production Status is set to Debugging, then there’s nothing wrong, and you can safely ignore them.

By itself, with no other symptoms, a Notice is not a bug, so please don’t report it as such.

On the other hand, if something is failing to work, the messages produced in debug mode might be helpful in tracking down the source of the problem.

How do I post tags and code on the forum?


When I try posting txp or HTML tags on the forum, they disappear. How do I post code examples on the forum?


For inline code:

@<txp:permlink><txp:title /></txp:permlink>@

For short snippets:

bc. <h3><txp:permlink><txp:title /></txp:permlink></h3>
<p><txp:posted /></p>

For longer snippets:

bc.. <txp:permlink><txp:title /></txp:permlink>
<p><txp:posted /></p>
<txp:body />

To post short Textile examples:



notextile. *Bold*

Or, for longer Textile examples:

notextile.. h1. My Title


If you’re still having trouble, or posting something long or complex, consider posting your code on and linking to that content from the forum.

Fatal error: xml_parser_create

Fatal error: Call to undefined function: xml_parser_create() in /htdocs/www/CMS/textpattern/lib/IXRClass.php on line 147

Textpattern requires the PHP XML library, which is enabled by default in PHP 4. It has been disabled on your server.

Some hosting companies (notably disable PHP XML by default, but allow individual users to turn it on in their PHP configuration. Please contact your host’s technical support if you need help with this.

If you’re running PHP on your own server, the installation instructions for PHP XML are listed on this page. Please note that installing and configuring a web server is outside the scope of the Textpattern support forum.

Notice: Constant txpinterface already defined..

This is usually caused by failing to upgrade all of Textpattern’s files. Make sure you don’t forget the index.php file that lives at the Textpattern root.

Non-ASCII characters are missing or incorrect


Some characters are replaced with question marks on my pages


This is most commonly caused by:

  • A missing DOCTYPE in your page template
  • A missing or incorrect character set in your page template
  • Using characters from a different character set (e.g. latin1 characters, when the charset is utf-8)
  • The mbstring.encoding_translation setting is turned on. This automatically converts all page output to some other character set, often ISO8859-1.

You can check the mbstring settings with php -i or phpinfo();. If mbstring.encoding_translation is on, ask your host about turning it off.

Textpattern has built-in support for Unicode. This means you don’t have to do anything special for non-ASCII characters to work. Just write articles using a modern browser, and enter any characters you like in the article title, body, and excerpt.

Don’t specify a legacy character set in your page doctype or HTML <meta> tags. The character set for all Textpattern pages should always be “utf-8”. If you use anything else, non-ASCII characters will be encoded incorrectly.

Problems with nested txp:if_.. tags


Some of my <txp:if_..> tags show up in the HTML output
Nested <txp:if_..> tags aren’t working as expected
Do nested tags work?


Textpattern version 4.0.7 and later supports nested tags (i.e. one tag inside another) without any constraint.

Older versions of Textpattern had limited capabilities in this area. Upgrading to the latest Textpattern release is the recommended solution.

Nesting a tag inside itself did not work in older Textpattern releases before 4.0.7:


If an upgrade is beyond consideration, there are other ways to nest tags: To work around the problem, put the inner block in a Misc form and use output_form, like this:

<txp:output_form form="myform" />



Fatal error: Call to undefined function..

Fatal error: Call to undefined function: formatmentionslink() in /home/somewhere/textpattern/lib/txplib_misc.php(429) : eval()’d code on line 172

Fatal error: Call to undefined function: checkcommentsallowed()

These and similar errors immediately after an upgrade are usually caused by one of two things:

  • Old plugins that haven’t been updated to work with the current version of Textpattern
  • Not updating or uploading all of Textpattern’s files correctly. Make sure you upload all the files in all subdirectories.

Similar errors immediately after installation usually indicate:

  • An incorrect txpath setting in config.php. The value automatically detected by the setup process is almost always correct, so don’t change it unless you know what you’re doing.
  • Textpattern .php files that are missing or in the wrong location.

Warning: failed to open stream..


Warning: failed to open stream..


Warning: main(/publish.php): failed to open stream: No such file or directory in /home/somewhere/textpattern/index.php on line 12

These and similar errors are usually caused by:

  • A missing or empty config.php file
  • Missing or empty subdirectories
  • Missing .php files
  • An incorrect ‘txpath’ setting in config.php

Make sure you’ve uploaded the complete contents of the Textpattern .zip/.tar.gz file to the correct location, and that your config.php settings are correct.

Warning: Unable to save result set..


Warning: mysql_query(): Unable to save result set..


Warning: mysql_query() [function.mysql-query]: Unable to save result set in /home/somewhere/public_html/blog/textpattern/lib/txplib_db.php on line 53

The “Unable to save result set” error is generally associated with major MySQL problems, like a corrupt table or faulty install. It is not caused by Textpattern.

In some cases we’ve found that repairing the MySQL database fixes this, even though CHECK TABLE reported no problems at all.

The PHP manual has a FAQ topic on a PHP installation problem that can cause this error.

The MySQL manual has a section on checking and repairing tables.

For TextDrive users, the TxD Knowledge Base has step-by-step instructions on how to repair a table.

If your hosting company provides phpMyAdmin, you can select a table, then use the “Repair table” option under the Operations tab.

There is also a Textpattern plugin which can allow you to repair tables in your Textpattern database.

Can I use PHP code in article bodies?

If the admin configuration option “allow_article_php_scripting” is on, < txp:php> @< /txp:php>@ is supported in article bodies. By default, PHP scripts are only run when the author of the article is a publisher or editor.

The user premissions required for PHP code in article bodies are defined in lib/admin_config.php, as 'article.php':

'article.php' => '1,2',

To allow different user levels to run PHP code in their articles, edit the levels (the comma-separated numbers) on that line. But be careful: this is a PHP file, so the syntax must be correct.


If you are using Textile, be sure to escape it:

notextile. <txp:php> // your PHP code </txp:php>

or you will end up with nasty errors like:

Parse error: parse error, unexpected ‘&’ in /path/to/your/site/textpattern/publish/taghandlers.php(2688) : eval()‘d code on line 2


By giving someone permission to run PHP code, you effectively give them permission to bypass all of Textpattern’s built-in security. Any user with permission to run PHP code can, intentionally or accidentally, modify or delete anything in your database, crash your site, and so on.

Using PHP code in Textpattern


Why doesn’t $thisarticle work in my PHP code?
<?php ... ?> doesn’t work anymore!


You can use PHP code in a Textpattern page template or form like this:

<txp:php>echo 'Hello world'; </txp:php>

Make sure you use <txp:php></txp:php> instead of <?php ... ?> or <? ... ?>.

There is an Advanced Preference that can be used to disable PHP code.

PHP code will also work inside an article body if Textpattern is configured to allow it. If you are using Textile, be sure to escape it:

notextile. <txp:php> // your PHP code </txp:php>

We strongly recommend you set your Production Status to Debugging when adding or modifying PHP code in Textpattern.

You can include() an external script, provided you understand how variable scope and include paths work. Your PHP code will not be executed in the global scope, so you’ll have to explicitly use the global keyword.

When including or opening a file from PHP, you’ll need
To see the current working directory and include path:

<txp:php>var_dump(getcwd(), get_include_path());</txp:php>

If your file resides in Textpattern’s admin folder, you can use the defined constant txpath to refer to that path – i.e. include(txpath.'/myfile.php');.

Please be aware that any PHP code you run from Textpattern, whether included directly in a page or in a separate file, will share database connections, function, variable and class names and so on with Textpattern. PHP doesn’t support separate namespaces, so it’s up to you to ensure there are no clashes.

Some caveats to be aware of when using <txp:php>:

Variable Scope

Your PHP code will not be executed in the global scope, so you’ll need to explicitly declare global variables as required. If you want to pass data between separate <txp:php> blocks, you’ll need to do something like this:

global $foo;

$foo = 'bar';
global $foo;

echo $foo;

Escaping to XHTML

While you can use multiple PHP blocks on a single page, each <txp:php>...</txp:php> block must be a valid block of code by itself. This means you can’t escape from PHP to HTML and back like you can with <?php ... ?>. This will not work:

<txp:php>if ($something) {</txp:php>

Use something like this instead:

if ($something) {
echo 'foo';


Other than the caveats listed above, Textpattern doesn’t interfere with your PHP code. If your code isn’t working as expected, you’ll need to use standard debugging techniques to find out what’s wrong.

If you’ve followed the recommendations above and set Production Status to Debug, Textpattern will set PHP’s error reporting settings to display all errors, warnings and notices. This should help you find errors like misnamed variables.

For other problems, the most effective debugging technique is also the simplest: good old fashioned debug printing. Use PHP functions like print(), var_dump() and var_export() to display important data at key points in your code.

Textpattern provides a handy function called dmp() that will display a message or array surrounded by <pre>...</pre> tags for easy viewing. For example:

dmp('My php code');

global $thisarticle;


dmp() uses the print_r() function to display arrays, and print() for everything else.

PHP debugging techniques are described in more detail in this article.

How do I reuse chunks of HTML?

  • Is there a way to reuse chunks of HTML like headers and footers?
  • How do I include small bits of static content in a page


Create a new form containing the chunk of HTML. Give it a name (say, “myform”). Set the type to Misc.

Now, anytime you want to reuse that form, use <txp:output_form form="myform" /> to display it.

Can I use txp tags in articles?


Can I use Textpattern tags in article bodies?


Some, but not all. In particular, <txp:article /> and <txp:article_custom /> usually won’t work at all, and are likely to fail in subtle ways if they do.

How do I manage static pages?


How do I create and manage static (non-blog) pages?
How do I create an “about” page, “contact” page, etc?


The short answer: create a section, use an article form that doesn’t include posted dates or permlinks, and post a single article in that section.

The long answer: when you view a URL like, Textpattern will display the section named contact, using the page template selected for the contact section. (This assumes your Textpattern front page is

The usual way to manage content on a “static” (single, stand-alone) page like this is as follows:

1. Create a new article form named static_article, with the following contents:

<h3><txp:title /></h3>
<p><i><txp:excerpt /></i></p>
<txp:body />

This will be used to display the article contents on your static page. You can change the markup later if you want.

2. Copy your default page template to a new template named static_page. Find the <txp:article /> tag in the static_page template, and change it to look like this:

<txp:article limit="1" form="static_article" status="sticky" />

This template will be used to display your static page.

3. Create a new section named contact (or whatever you want your page to be called). Go to presentation > sections and set Uses page to static_page for your new section.

4. Post a new article in the contact section, with the article status set to Sticky instead of Live.

The most recent Sticky article will be displayed as the page contents when you view the URL

To create additional static pages, you can skip steps 1 and 2, and reuse the same static_page template.

For the best way to create links to your static pages, see How do I create navigation links?

For a more detailed description, read Managing Static Pages With Textpattern

How do I display time and date formats in my local language?

The date and time functions used by Textpattern will automatically translate month and day names, provided the locale is set correctly, and provided your server supports it.

If you’ve selected the appropriate language in textpattern > admin > preferences and are still not seeing dates in your language, it most probably means that your web server’s operating system has limited support for your language. You should ask your hosting company to upgrade their locale support.

To use a different format for article dates, use the <txp:posted format="..." /> attribute. See here for more details.

To display an article date using a different language to the main Textpattern language, the following code will work on some systems:

global $locale;
setlocale(LC_ALL, 'nl_NL.UTF-8');
echo posted(array('format' => '%A %B %e %Y, %H:%M:%S'));
setlocale(LC_ALL, $locale);

You’ll need to change the locale string (nl_NL.UTF-8) and format to suit.

How do I use a custom date format?


None of the date formats match the standard ones used in my locale.
My favorite date/time format isn’t in the list!
How do I use a custom date format for article or comment timestamps?


Use <txp:posted format="%Y-%m-%d" /> or similar. See the PHP manual for a list of format specifiers.

Please note that Windows supports only a limited subset of format specifiers.

For information about displaying times and dates in different languages, see How do I display time and date formats in my local language?.

My dates look like 'Y m d'!

QUESTION:<txp:posted format="Y-m-d" /> doesn’t work!
My timestamp formats are broken after upgrading – they all show “Y-m-d”!


The format characters changed around the RC3 release. The date() formats like ‘Y-m-d’ no longer work; they now use strftime() format characters instead.

The simplest fix is to go to textpattern > admin > preferences, select a new date format, and save the settings.

Why aren't the right articles showing up on my page?


Why isn’t search working properly?
New articles don’t show up on my front page
Section and category browsing doesn’t work
‘older’ and ‘newer’ links don’t work


These and similar problems are most commonly caused by replacing the <txp:article /> tag with <txp:article_custom />.

Always use <txp:article /> as the main article tag on your page. <txp:article_custom /> is for specialized use such as sidebars; think of it as an advanced version of <txp:recent_articles />.

For more information about the difference between the two tags, see FAQ: What does article_custom do?.

How do I change the output of txp:recent_articles?

Use <txp:article_custom /> instead, and create or edit a form to control the output. You can use any article tag in that form: <txp:title />, <txp:posted />, etc.

For detailed examples, see Customizing txp:recent_articles.

How do I show only an excerpt in article lists?


How do I show excerpts in article lists, and the full text on each article page?
How do I show a “read more” link for each article?
How do I use a different layout for article lists and invidividual article pages?


Textpattern provides two main text fields per article: the Body and the Excerpt. The Body is the main article content. The Excerpt is normally used for a summary, introductory paragraph, abstract or similar.

To implement a “Read More” link, we’ll display the Excerpt on list pages (such as the front page and section pages), and the Body on the individual article (‘permlink’) pages. There are two ways to do this: one by using separate forms for the list and article pages; and another by using a single article form with a <txp:if_article_list> tag.

Method 1:

Use two article forms: one that shows only the excerpt, and one that shows the full article. Your main article form (typically ‘default’) would normally contain a <txp:body /> tag, which displays the complete article.

Create a new article form named “excerpt”, containing something like this:

<txp:excerpt />
<txp:permlink>read more</txp:permlink>

Your default form normally contains something like this (edited for brevity):

<h3><txp:permlink><txp:title /></txp:permlink></h3>
<txp:excerpt />
<txp:body />

In your page template, use <txp:article form="default" listform="excerpt" />.

This means that the default form will be used for full article pages, and the excerpt form will be used for list pages. To change the appearance of either page (e.g. to remove the excerpt from the full article page), edit the appropriate form.

(For more information the article tag and forms, see ‘How do I select which form is used to display articles?’)

Method 2:

Use an article form, containing something like this:

<! -- list page: display the short version -- >
<txp:excerpt />
<txp:permlink>read more</txp:permlink>
<txp:else />
<! -- article page: display the complete article -- >
<txp:body />

If you want to include the excerpt as well as the body on the article page, just add a <txp:excerpt /> tag above <txp:body />.

Conditional Layout

With either of the above methods, you can use the <txp:if_excerpt> tag inside the article form to lay out articles with and without excerpts differently. For example, to apply separate CSS classes to the excerpt and body:

<! -- this article has an excerpt -- >
<div class="excerpt">
<txp:excerpt />
</txp:if_excerpt />
<div class="body">
<txp:body />

The same txp:if_excerpt tag can be used on the list page to handle articles that have no Excerpt set. For example, to display the article Body when the Excerpt is empty:

<! -- the article has an excerpt -- >
<txp:excerpt />
<txp:permlink>read more</txp:permlink>
<txp:else />
<! -- there is no excerpt -- >
<txp:body />

If you need to automatically generate an Excerpt from the Body, there are several plugins that will help. You’ll find them at Textpattern Resources or on the Textpattern Plugins Forum.

How do I use a different page layout for individual articles and article lists?

Use <txp:if_individual_article> </txp:if_individual_article> and <txp:if_article_list> </txp:if_article_list> in your page template or form.

How do I use a different page layout for each section?

Create multiple templates in presentation > pages, then change the “Uses page:” option for each section in presentation > sections.

You can also select the CSS stylesheet individually for each section.

How do I select which form is used to display articles?

The form used to display articles is specified by the <txp:article /> tag in your page template. In the default template it looks similar to this:

<!-- center -->
<div id="content">
<txp:article />

To display articles using a different form, change the <txp:article /> tag to specify the form name like this:

<txp:article form="myform" />

If no form="..." attribute is specified, <txp:article /> will look for an article from named “default”.

You can specify separate forms for list pages and individual article pages like this:

<txp:article listform="short" form="long" />

It’s also possible to use a different form for a single article, using the Override form selection under Advanced Options on the content > write page.

How do I change the grey line separating articles?


How do I change the layout of an article?


The layout of each article is controlled by a form. Go to textpattern > presentation > forms and edit the one used by your page template (probably ‘default’, unless you’ve changed it).

Alternatively, you can create a new article form and use that to display articles. For more information, see ‘How do I select which form is used to display articles?’