Yelp » Tools »

yelp-build

yelp-build cache

Create a Mallard cache file from a Mallard document. A cache file is necessary to build other formats from Mallard documents. The other build commands generate a cache file automatically, but sometimes it's useful to provide a cache file explicitly. For example, if you only want to output the HTML for one page, you might run:

yelp-build html foo.page

But then yelp-build will assume that foo.page is the entirety of the document, and will create a cache file for just that page. If you have a cache file with the cache for all pages, say index.cache, you can instead run:

yelp-build html -c index.cache foo.page

You can pass yelp-build cache a list of page files, or just pass it a directory to have it cache all page files in that directory.

yelp-build cache *.page
yelp-build cache .

By default, the output cache file name is index.cache. Use the -o option to output a different file name.

yelp-build cache -o foo.cache .

yelp-build epub

Output an EPUB file, currently for Mallard documents only. An EPUB file is a special zip file containing XHTML files, stylesheets and other supporting files, and EPUB-specific files that specify the document structure. You can pass yelp-build epub a list of page files, or just pass it a directory to have it use all page files in that directory.

Just as for yelp-build html or yelp-build xhtml, you can pass a custom cache file with the -c option, a customization stylesheet with the -x option, a path for external files with the -p option, and the option to ignore missing media files with -i. See the documentation for yelp-build html for more information. Note that setting URL roots for JavaScript, CSS, and icon files is usually not a good idea for EPUB, because yelp-build epub places those files in a fixed location inside the zip file.

By default, the output file name is index.epub. Use the -o option to specify a different output file.

yelp-build html

Output HTML files from a Mallard or DocBook document. The output file names are taken from the IDs in the XML, regardless of the input file names. For Mallard, you can pass yelp-build html a list of page files, or just pass it a directory to have it create HTML for all page files in that directory. For DocBook, pass the top-level XML file.

yelp-build html index.page foo.page bar.page
yelp-build html .
yelp-build html index.docbook

By default, files are output to the current working directory. Use the -o option to specify an output directory.

mkdir html_out
yelp-build html -o html_out .

If you use the -o option, yelp-build html will also copy media files to the output directory and create the appropriate directory structure under the output directory. It will look inside the XML for tags like media and imagedata to find media files to copy.

Sometimes, some media files and external resources are not under the same path. This happens, for example, when you generate translated files in another directory but don't create copies of untranslated files. Pass a path of other base directories to use for files lookups with the -p option to resolve these files.

If a referenced media file does not exist (potentially anywhere within the path), yelp-build will still attempt to copy it, which will produce warnings on stderr. To make yelp-build check for the file's existence before copying, use the -i option. Be careful: without the warnings, you could easily end up with broken images in your document.

For Mallard documents, a cache file is created for you by default from the pages you pass on the command line. You can also pass a cache file explicitly with the -c option. This is useful if you only want to rebuild a few pages, but you want yelp-build to know about all the pages in the document for linking purposes. See yelp-build cache above.

When creating HTML, yelp-build also outputs CSS and JavaScript files, as well as PNG files for icons and watermarks. What it outputs depends on what's in your document. For JavaScript, a static set of files are copied, as well as additional JavaScript files for syntax highlighting. Which files are copied depends on what syntaxes you use in program listings and code blocks. For CSS, yelp-build creates a separate CSS file for each top-level language. For icons and watermarks, which images are copied depends on what types of admonitions and other elements you use.

The stylesheets that do the conversion to HTML are flexible and customizable. You can add customizations to affect the layout and presentation. You can pass a customization stylesheet to yelp-build html using the -x option.

yelp-build html -x custom.xsl .

The customization stylesheet should not include or import the Yelp stylesheets. The yelp-build command will automatically create a wrapper stylesheet that includes the customization and imports the Yelp stylesheets. For information about the extension points and how to customize the stylesheets, see Yelp XSL.

The stylesheets allow you to specify URL roots for CSS, JavaScript, and icon files. By default, it's the same directory as the output HTML files. You can override these by setting parameters in a customization stylesheet, but yelp-build html does not change where it outputs those files. If you set these parameters to use common files on your web site, you must manage those files manually.

yelp-build xhtml

Output XHTML files from a Mallard or DocBook document. This works exaclty like the yelp-build html command and allows the same options, but it serializes the files as XML. See the documentation for yelp-build html for details.