Wyam - Modules - WriteFiles

WriteFiles

Writes the content of each input document to the file system.
If the metadata keys WriteFileName (which requires RelativeFileDir to be set, usually by the ReadFiles module), WriteExtension (which requires RelativeFilePath to be set, usually by the Wyam.Core.Modules.IO.ReadFiles module) or WritePath are set on an input document, that value will be used instead of what's specified in the module. For example, if you have a bunch of Razor .cshtml files that need to be rendered to .html files but one of them should be output as a .xml file instead, define the WriteExtension metadata value in the front matter of the page.

Usage

  • WriteFiles()

    Writes the document content to disk with the same file name and relative path as the input file. This requires metadata for RelativeFilePath to be set, which is done by the Wyam.Core.Modules.IO.ReadFiles module or can be set manually.

  • WriteFiles(DocumentConfig path)

    Uses a delegate to describe where to write the content of each document. The output of the function should be either a full path to the disk location (including file name) or a path relative to the output folder.

    • path

      A delegate that returns a Wyam.Common.IO.FilePath with the desired path.

  • WriteFiles(string extension)

    Writes the document content to disk with the specified extension with the same base file name and relative path as the input file. This requires metadata for RelativeFilePath to be set (which is done by default by the Wyam.Core.Modules.IO.ReadFiles module).

    • extension

      The extension to use for writing the file.

Fluent Methods

Chain these methods together after the constructor to modify behavior.

  • Append(bool append = true)

    Appends content to each file instead of overwriting them.

    • append

      Appends to existing files if set to true.

  • IgnoreEmptyContent(bool ignoreEmptyContent = true)

    Ignores documents with empty content, which is the default behavior.

    • ignoreEmptyContent

      If set to true, documents with empty content will be ignored.

  • OnlyMetadata(bool onlyMetadata = true)

    Indicates that only metadata should be added to the document and a file should not actually be written to the file system. This is useful for preprocessing documents so they appear in a pipeline with the correct write metadata, while actually writing them later with a second Wyam.Core.Modules.IO.WriteFiles module invocation. Only the following metadata values are written when this flag is turned on: WritePath, RelativeFilePath, RelativeFilePathBase, and RelativeFileDir. The Destination... metadata values are not added to the document when only setting metadata..

    • onlyMetadata

      If set to true, metadata will be added to the input document(s) without actually writing them to the file system.

  • UseWriteMetadata(bool useWriteMetadata = true)

    By default the metadata values for WritePath, WriteFileName, and WriteExtension are checked and used first, even if a delegate is specified in the constructor. This method can be used to turn off the default behavior and always rely on the delegate for obtaining the write location.

    • useWriteMetadata

      If set to false, metadata of the input document will not be used.

  • Where(DocumentConfig predicate)

    Specifies a predicate that must be satisfied for the file to be written.

    • predicate

      A predicate that returns true if the file should be written.

Input Metadata

The metadata values listed below apply to individual documents and are typically set from front matter (with just the name of the key) and used as inputs to the module to control behavior.

  • Keys.RelativeFileDir: Wyam.Common.IO.DirectoryPath

    Used in combination with Wyam.Common.Meta.Keys.WriteFileName to determine an alternate location to write the file.

  • Keys.RelativeFilePath: Wyam.Common.IO.FilePath

    Used in combination with Wyam.Common.Meta.Keys.WriteExtension to determine an alternate location to write the file.

  • Keys.WriteExtension: System.String

    The extension to use when writing the file.

  • Keys.WriteFileName: Wyam.Common.IO.FilePath

    The file name to use when writing the file.

  • Keys.WritePath: Wyam.Common.IO.FilePath

    The path to use when writing the file.

Output Metadata

The metadata values listed below apply to individual documents and are created and set by the module as indicated in their descriptions.

  • Keys.DestinationFileBase: Wyam.Common.IO.FilePath

    The file name without any extension. Equivalent to Path.GetFileNameWithoutExtension(DestinationFilePath).

  • Keys.DestinationFileDir: Wyam.Common.IO.DirectoryPath

    The full absolute directory of the file. Equivalent to Path.GetDirectoryName(DestinationFilePath).

  • Keys.DestinationFileExt: System.String

    The extension of the file. Equivalent to Path.GetExtension(DestinationFilePath).

  • Keys.DestinationFileName: Wyam.Common.IO.FilePath

    The full file name. Equivalent to Path.GetFileName(DestinationFilePath).

  • Keys.DestinationFilePath: Wyam.Common.IO.FilePath

    The full absolute path (including file name) of the destination file.

  • Keys.DestinationFilePathBase: Wyam.Common.IO.FilePath

    The full absolute path (including file name) of the destination file without the file extension.

  • Keys.RelativeFileDir: Wyam.Common.IO.DirectoryPath

    The path to the folder containing the file relative to the input folder.

  • Keys.RelativeFilePath: Wyam.Common.IO.FilePath

    The path to the file relative to the input folder. This metadata value is used when generating links to the document.

  • Keys.RelativeFilePathBase: Wyam.Common.IO.FilePath

    The path to the file relative to the input folder without extension.

  • Keys.WritePath: Wyam.Common.IO.FilePath

    The write path is output if the module is in metadata-only mode so that following executions of the Wyam.Core.Modules.IO.WriteFiles module will write the document to the calculated output path.

GitHub