Pintail - Build web sites from Mallard sources
Pintail is a tool that automates building entire web sites from Mallard sources.
Normally, a Mallard document consists of all the pages within a single directory.
Pages can refer to each other by ID using the
xref attribute of the
element. Pintail allows multiple directories, and extends the
to allow referencing pages in other directories.
Pintail uses Python setuptools to build and install. Pintail is Python-3-only, so to build and install:
python3 setup.py build sudo python3 setup.py install
Or to get the latest version uploaded to pypi:
pip-python3 install pintail
python3-lxmlto transform Mallard pages
into HTML. Both packages are available on all major Linux distributions, and
yelp-xslis installed by default on most. You will likely need to use your package
manager to install
python3-lxml. If using a Mac, use MacPorts to install
yelp-xsl. (Future versions will download
yelp-xsl automatically if
necessary. See issue #8.)
To start using Pintail, run
pintail init in the top-level directory for your
site. This may be a new empty directory or a directory already populated with
Mallard page files. This command will create a sample
pintail.cfg file. Edit
this file to customize your site.
Create Mallard page files. If you're new to Mallard, check out the [tutorials]
(http://projectmallard.org/about/learn/) on projectmallard.org. Anything you
can do in Mallard, you can do with Pintail. And since Pintail builds on the
yelp-xsl stylesheets, any extensions supported by Yelp are also
supported by Pintail.
To build a site, run
pintail build. This will build all HTML, CSS, and
need to upload to your server. Images and videos found automatically by
looking in the Mallard page files. You can specify more files using the
extra_files configuration key.
You can also regenerate only particular parts of the site. For example,
you can use
pintail css to build only the CSS files, which is useful
when iterating on the design. See
pintail --help for more options.
You can also pass
--local to build files more suitable for local viewing.
This automatically sets the site root to the build directory, and you can
specify different values for various configuration options.
The Pintail configuration file is a simple INI file. Site-level options
are in the
[pintail] site_root = / html_extension = .html custom_xsl = mycustom.xsl
You can also override any site-level options in the
These values will be used instead when you pass
You can specify options for each directory by adding a group with the directory's path. The path must begin and end with a slash.
[/downloads/] extra_files = mypackage.zip
Pintail extends Mallard to allow referencing pages outside the same directory. As with stock Mallard, all pages in a single directory are part of a document, and so page IDs must be unique within each directory. Page IDs to not have to be unique across an entire site.
To reference a page in a different directory, put the directory path
before the target page ID, starting with a slash,
Pintail also adds a type for the
(This should be changed to
site:subdirs. See issue #9.) This will
create a list of links to the index page of each immediate subdirectory
of the directory of the current page.