---
title: Webgen::SourceHandler::Virtual
---
## Description

This source handler uses files in [Webgen Page Format]({relocatable: ../webgen_page_format.html})
which are used to specify virtual paths. Virtual paths don't really exist as source paths but are
useful nonetheless. For example, they allow to include links to external content in automatically
generated menus. They are never written out since they define no real content!

The `content` block of the source path is used and its content needs to be a hash in YAML
format. The keys are relative or absolute source paths names and the values meta information for
them. Any meta information can be set on a virtual path but one meta information key is special:
`url`. This meta information specifies, relative to the directory in which the source file is in,
the output path for the virtual node. If no `url` meta information is specified, the source path
itself is used as output path.

Following is a sample virtual source files with explanations afterwards:

    \--- !omap
    - /documentation/:

    - /documentation/index.html:
        routed_title: Documentation

    - download_and_installation.html:
        in_menu: true
        sort_info: 25
        url: index.html#download__installation

    - /documentation/api.html:
        title: API Reference
        url: http://myhost.com/api

> The example does not use a normal hash but an ordered YAML map. This ensures that the virtual
> nodes are created in the order they appear in the file.
{.information}

The first entry specifies that a directory `/documentation` should be created. The virtual file
handler recognizes this because the given path ends in a slash!. Then a virtual index file for the
virtual directory is created. This would be done, for example, when the documentation directory is
created by an external program.

The third entry specifies a virtual file that should in the menu and should have a certain sort
information. When this virtual file is referenced, the path given by the `url` key is returned. This
example shows how to make a single link to a fragment appear in automatically generated menus.

And the fourth entry specifies another virtual file whose output path is an URL pointing to
`http://myhost.com/api`.