Single Template Local Projects
A doxx project in its simplest form includes two mandatory files, a key file and a local template file.
├── project-directory ├── key.yaml # doxx key file └── example.doxt # doxx template file
With these two files, a single rendered file is generated when a user executes
doxx build in the project directory.
Multi-Template Local Projects
Multi-text file projects are developed with multiple template files. Template files map one-to-one with rendered text files and can specify any sub-directory structure within the project directory. The destination directory, file name, and file extension are defined in the template build specification header section. Please refer to the template documentation for additional details.
Here's an example of a two template project where the template files are located in a templates project sub-directory. The key.yaml file remains in the top level project directory and defines the root directory for builds.
├── project-directory ├── key.yaml # doxx key file └── templates ├── example.doxt # doxx template #1 └── example2.doxt # doxx template #2
File writes take place according to template specifications relative to the location of the key file, not the template file(s). This allows the template files to be stored on any path (including on remote file servers accessible by GET request, see below).
The above project will write two text files according to the developer's specifications in the template files and the user's replacement strings in the key file.
Remote Template Projects
doxx reads remote template files through GET requests using the http:// or https:// protocol. Developers can store their templates on a remote file server and provide users with the URL to access the templates. The URLs are included in the user's key file in order to build the project. This allows a user to drop a key file into a new project directory and build without local template files.
├── project-directory └── key.yaml # doxx key file
The project directory structure is preserved because the build takes place relative to the key file according to paths that are specified in the template files. The user executes
doxx build in their project directory and the file writes take place locally with the appropriate file paths. New sub-directories are created as necessary to accommodate the new file paths.
Project archives allow developers to design much more complex projects and distribute these as a single archive file. These project archives can include text template files that allow for text string replacements, text files that write verbatim to disk, and binary files. These are distributed as tar.gz or zip archives and can be used in place of multiple template paths (or URLs) for project builds. Like template files they can be stored locally or on remote file servers accessible by GET request.
The project archive file structure differs slightly from the template projects described above. It includes two mandatory files: project.yaml and a template file.
├── project-directory ├── project.yaml # doxx project specs file └── templates └── example.doxt # doxx template file
While optional, the addition of a pkey.yaml file in your project archive is of benefit to users because it allows the them to
doxx pull the project archive and use the pkey.yaml file (which incidentally is renamed
key.yaml during the pull if a
key.yaml file does not already exist in the working directory) as their key file stub. It has the same syntax and serves the same function as the key.yaml file. The file name differs when included in a project archive so that it does not overwrite an existing user key.yaml file in the root directory.
├── project-directory ├── pkey.yaml # doxx project key file ├── project.yaml # doxx project specs file └── templates └── example.doxt # doxx template file
The above example demonstrates a minimal project archive structure. By building on these required files, it is possible to create projects of increased complexity.
For instance, an HTML project that provides templates for the index.html, main style sheet, and main JS files might take the following structure:
├── project-directory ├── pkey.yaml ├── project.yaml ├── 404.html ├── apple-touch-icon-precomposed.png ├── crossdomain.xml ├── css │ └── normalize.min.css ├── favicon.ico ├── humans.txt ├── index.html ├── js │ ├── jquery.min.js │ ├── modernizr.min.js │ └── plugins.js ├── robots.txt └── templates ├── index.doxt ├── maincss.doxt └── mainjs.doxt
Once the project files are complete, the directory is packaged as a tar.gz or zip archive. doxx provides the
pack command to create both of these archive types. If you store the project archive on a remote repository, users can
doxx pull the project archive file, examine the unpacked contents, enter their text replacement definitions in the key.yaml file (renamed from the project archive pkey.yaml file if key.yaml was not present at the time of the pull), and build with the pulled template files.
Project archive file specs and additional information on usage are available in the project archive documentation.