Upgrading your Textile posts to Markdown
A month ago, we announced that GitHub Pages had upgraded to Jekyll 3.0. Starting May 1st, 2016, GitHub Pages will no longer support Textile. If you are currently using Textile…
![](https://github.blog/wp-content/uploads/2019/03/company-twitter.png?resize=1201%2C630)
A month ago, we announced that GitHub Pages had upgraded to Jekyll 3.0.
Starting May 1st, 2016, GitHub Pages will no longer support Textile. If you are currently using Textile (Redcloth) to author your Jekyll site, you’ll need to convert your site to use Markdown instead.
Here are some tips for converting from Textile to Markdown.
Manual conversion
On sites with just a few Textile pages, editing those by hand may be the fastest way to convert to Markdown. Here are some of the most important changes.
Textile | Markdown | |
---|---|---|
headings | h1. text |
# text |
h2. text |
## text |
|
h3. text |
### text |
|
links | "link-text (title)":url |
[link-text](url "title") |
bullet lists | * item |
* item |
** nested item |
* indent nested item
|
|
numbered lists | # item |
1. item |
## nested item |
1. indent nested item
|
|
italics | _italics_ |
_italics_ |
bold | *bold* |
**bold** |
code |
<code> code </code> |
|
blockquotes | bq. text... |
> text... |
For more details refer to the Textile docs and the GFM cheatsheet
Automated conversion from .textile to .md with pandoc
Users with many Textile files in their Jekyll Pages site can leverage pandoc, a utility for converting between different markup formats.
The tomd
shell script uses awk and sed to overcome the biggest limitations of pandoc, filtering out the sections listed below, which pandoc doesn’t recognize, and re-inserting them into the converted Markdown.
- YAML frontmatter at the top of .textile files
-
{% raw %}{% highlight %}{% endraw %}
blocks -
<notextile>
blocks
To run tomd
- Install pandoc from https://github.com/jgm/pandoc/releases or here.
- Download or clone tomd.
- Copy the
tomd
script and the two.awk
files into your Jekyll project. - Invoke the script with
./tomd
from inside your Jekyll project folder. - Validate the results.
The script will look for any .textile
files in the _posts
directory, convert them to .md
, and leave backups of the original .textile
files in a new directory called _old_posts
. You can override the names of the directories with arguments to the script.
If everything works, you will see output like:
NOTE: This process may still produce some incorrect output, so check your results.
Known issues include:
- Lost CSS references e.g. from Textile
.p(classname)
- Literal HTML mixed with Textile formatting e.g.
<sup>"textile-link-text":url</sup>
Running under Windows
The latest version of pandoc for Windows can be downloaded from https://github.com/jgm/pandoc/releases/.
In addition to pandoc, tomd
requires a unix-y shell and utilities. The easiest way to get those for Windows is by installing the default set of cygwin utilities.
Before running tomd, use cygwin dos2unix
and run it against the tomd
file to remove extra linefeeds.
The output of running tomd
in the cygwin shell should look very similar to the OSX output above.
Tags:
Written by
Related posts
![](https://github.blog/wp-content/uploads/2024/05/GitHub-for-beginners.png?resize=400%2C212)
Beginner’s guide to GitHub: Merging a pull request
As part of the GitHub for Beginners guide, learn how to merge pull requests. This will enable you to resolve conflicts when they arise.
![](https://github.blog/wp-content/uploads/2024/08/github-cli-header.png?resize=400%2C212)
How to level up your Git game with GitHub CLI
Using Git in the CLI can improve your development speed and power. Here are our top eight commands for using GitHub via your command line.
![](https://github.blog/wp-content/uploads/2024/05/GitHub-for-beginners.png?resize=400%2C212)
Beginner’s guide to GitHub: Creating a pull request
As part of the GitHub for Beginners guide, learn how to create pull requests. This will enable you to suggest changes to existing repositories.