Configuration for Tapestry is stored in either PHP or YAML format within the root of your project workspace. By default Tapestry initiates a new project workspace with a config.php, however you can replace that with config.yaml if you wish to use YAML to configure Tapestry.

Environment Configuration

It's often helpful to have different configuration values based upon the environment that your static site is being hosted on. For example the base url will be different when developing from localhost:8000 to when you deploy to your web hosting.

The build command accepts the current environment through the --env option, this defaults to local when not defined.

Configuration Load Order

When Tapestry initiates it loads default configuration from its core DefaultConfig.php. It then looks in the project workspace for the existence of and loads if found config.php|yaml. Finally Tapestry then looks for and loads if found config-{env}.php|yaml.

This load order allows you the freedom to define constants within config.php|yaml and then per environment overloads within config-{env}.php|yaml.

Accessing Configuration Values

To assist in accessing configuration values from your phtml templates Tapestry provides a site helper. This allows access to any configuration you set within the site config namespace.

For example, the configuration for this website defines the following:

return [
    'site' => [
        'title' => '',
        'url' => 'http://localhost:3000',
        'description' => 'Tapestry static site generator.',
        // ...

Everything within the site namespace is available from the websites template files via the site helper, for example if I wanted to output the site title I could do: <?= $this->site('title') ?>.

Core Configuration Values

The default configuration for Tapestry is defined within DefaultConfig.php.


This configuration option currently does nothing, the idea is that when true it would allow for stack traces to be output into your html for debugging; however currently these are output to your console before Tapestry exits.

Default: false

Currently marked as deprecated.


The workspace kernel to be loaded during site building; this is the class that you use to extend Tapestry and insert your own extensions and functionality, for more information see here.

Default: \Tapestry\Modules\Kernel\DefaultKernel::class

Pretty Permalinks

Enable / Disable pretty permalink, if true then / will be written as /about/ This may be over-ridden on a per file basis.

Default: true

Publish Drafts

Enable / Disable the publishing of files with draft: true in their front matter. You may want to set this as true in your development environment configuration so you can preview draft posts.

Default: false

Content Types

By default Tapestry is configured with a blog content type, for more detailed information on configuring Content Types and how to use them click here.

Content Renderers

By default Tapestry comes with four content renderers built in, these can convert the following input formats into HTML:

  • phtmlPHP Plates template files
  • htmlraw HTML content files
  • mdmarkdown content files
  • defaultall other files which get copied rather than rendered

Click here for more detailed information on the inner workings of content renderers and how to extend Tapestry with your own.

Content Generators

By default Tapestry comes with four content generators built in, these provide the following functionality:

  • PaginationGenerator — this takes an input collection and paginates it, generating each page as necessary and injecting a pagination object.
  • TaxonomyArchiveGenerator — this generates taxonomy archive pages, for example one page for each unique category used within a content type. This can be paired with the PaginationGenerator to generate paginated archive pages.
  • TaxonomyIndexGenerator — currently this generator is a placeholder demo for functionality. It currently does nothing beyond piping through to the next generator if one is defined.
  • CollectionItemGenerator — this generator takes an input collection of content and generates pages for each item, each generated page is injected with that items siblings allowing for it to be aware of previous and next items.

Click here for more detailed information on the inner workings of content generators and how to extend Tapestry with your own.


This contains an array of paths to ignore and not parse, any path matching those listed will be ignored by Tapestry during its initial file scraping (this does not limit additional plugins/modules unless they choose to abide by it.)

Default: ['_assets']


Paths that have been ignored, but which should be copied 1-to-1 from source to destination. This is useful for ensuring that assets are copied, but are not parsed (which would slow things down with many files.)

Default: []