doxx Project Archives

What is a Project Archive File?

Project archive files are tar.gz or zip archives of a doxx project directory. These archives wrap all project build files under a single filename. doxx can build directly from a project archive file which simplifies the path settings in a user's local key file for large projects with complex directory structures. Project archives also permit distribution of binary files (e.g. image files, audio files, PDF files) in addition to the text files specified in project templates.

Project Archive Directory Structure

The required files in a project archive differ slightly from a non-archived project.

Project Archives Include:

  • pkey.yaml key file
  • project.yaml build spec file
  • one or more template files
  • any number of verbatim text files and/or binary files
  • project-specific directory structure

The pkey.yaml File

The pkey.yaml file

  • replaces key.yaml in a project archive.
  • has the same structure as a key.yaml file

An archived project includes a key file that is named pkey.yaml rather than key.yaml. This is to avoid collisions with local user key files when an archive is unpacked into a local build directory. If doxx pull is used to pull and unpack a remote archive file, the pkey.yaml file is renamed key.yaml if the file is not already present in the user's working directory. If the file is already present, it is assumed that the user wants to preserve their existing key.yaml file and pkey.yaml writes to the directory.

By default, builds always take place from key.yaml when doxx build is used without an argument and there is no exception with unpacked project archives. If a user must build from the pkey.yaml file, you must explicitly state this in your build instructions because it will not take place by default if they have generated their own key.yaml file.

pkey.yaml build specification header sections can include any build specification field except project: and employ the same build spec syntax as key.yaml files. Please see the key file documentation for more details.

The project.yaml File

The project.yaml file:

  • defines the project build file paths
  • is used when builds take place directly with the project archive file without previously unpacking it
  • includes only the build specification head section of a standard key file

The project.yaml file defines the local project template files to be used when a user builds directly from a project archive file without previously pulling and unpacking the entire project. The file includes the build specification header section of a standard doxx key file without a text replacement definition section.

Here's an example of a properly formatted project.yaml file:

---

templates: [example.doxt, example2.doxt, example3.doxt]

---

Template Files

Template files in project archives have the same standard format that is described in the Templates section of the documentation.

Project Archive File Distribution

Project archive builds:

  • can be performed directly with local or remote project archive files (tar.gz or zip)
  • can be performed after a user unpacks a project archive file

doxx supports builds from local or remote project archive files with the doxx build command. Remote project archives must be accessible to doxx by GET request using the http:// or https:// protocol.

To build directly from a project archive file, the key file should include the project: build spec field with either a local file path or a URL to the project archive file (see key file documentation). For this type of build, the user will be expected to generate a key.yaml file in the build root directory. They can either make this file themselves or one can be distributed to them outside of the project archive file. The user executes doxx build with key.yaml in the root of the new project directory to initiate the project build from the archive file.

It is also possible to unpack a project archive prior to the build. doxx provides the doxx pull command which pulls remote archive files to the local machine and unpacks them in the current working directory. There is also cross-platform (including Windows) support for local tar.gz and .zip archive decompression and unpacking with the doxx unpack command if project users obtain the archive file in a different way (e.g. browser download). With this form of project distribution, the key file should specify local template files with either the template: or templates: build spec field rather defining a project archive file with the project: field. The benefits of this approach are that the user can examine the contents of the project prior to the build and a key file stub can be packaged in the archive for use in the build. The user completes the key file and uses doxx build to initiate the build from the unpacked project files.

doxx pack (docs) can be used to create tar.gz or zip archives of your project.

doxx unpack (docs) can be used to unpack tar.gz or zip archive files.

doxx pull (docs) pulls a remote project archive file and unpacks it in the current working directory.


just blimpin doxx documentation is licensed under the CC-4.0-Attribution LicenseImprove this page