Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
235 lines (123 sloc) 15.1 KB

doxx header image doxx text file templating, build, and distribution system

A simple, flexible text templating, build, & project distribution system

just blimpin What is doxx?

Build and Distribute Your Own Projects

doxx is a generic text file project build and distribution system that can be used to distribute any project that includes text files. It supports simple YAML formatted build specs and build time text file customization using local or remote text templates (that can be hosted on any publicly accessible server). Use it to create reusable templated text projects for yourself, or as a personal package manager to distribute your projects to the masses. And there is absolutely no programming experience required to use it.

And Take Advantage of Projects Built By Others

Pre-Built Projects in the Package Repository

The doxx Package Repository contains a growing list of ready-made, common project types that that are generated with a simple set of doxx commands. It provides a quick way to build popular projects like Bootstrap and Foundation HTML frameworks, the Font Awesome CSS library, Chrome browser extensions, Ionic mobile framework driven apps, angular.js driven sites, Phaser framework powered games, software licenses, and much more.

See the User Quickstart Guide to get started.

Simple Github Repository Pulls with Pull Shortcodes

Pull an entire Github repository into your project, or cherry pick files and directories from a Github repository with doxx pull shortcodes. There are no git, cURL, or node.js dependencies and they work on Linux, Unix (including Mac OSX), and Windows systems.

Check out the shortcode overview tutorial and the file and directory cherry-picking tutorial for more information.

Fresh From the Lab:

New textfiles Build Spec Field

Track text files in a Github repository branch or any other GET request accessible site and include the always current version when your project is built.

A tutorial is available on this new key file build spec field and more detailed information is located in the key file documentation.

Faster Builds

The v0.9.4 release includes build performance updates. Current users can update with the command:

$ pip install --upgrade doxx

Check out the Twitter feed for additional updates and tips.

cruisin Features

For Project Users

Simple Project Builds

Enter your text replacements in a key file, then build your version of a project with the command:

$ doxx build

Simple, Legible Text Replacement Definition Files

Text replacements are defined with simple YAML syntax:

name: Chris
version: 1.0
project-name: doxx

Build Anywhere

doxx supports remote storage of template files and builds directly from the remote files. You can build new projects on any system with internet access.

Cherry Pick Files and Directories from Github

Fill out your project structure with anything from complete Github repositories to a single file contained in a repository.

Pull the master branch of a Github repository:
$ doxx pull FortAwesome/Font-Awesome
Pull a different branch / release from a Github repository:
$ doxx pull FortAwesome/Font-Awesome:v4.2.0
Pull a single repository directory from a release:
$ doxx pull FortAwesome/Font-Awesome:v4.2.0+css
Or just keep a single file that you need:
$ doxx pull FortAwesome/Font-Awesome:v4.2.0+css/font-awesome.min.css

Don't Know cURL, git, tar, zip?

Everything that you need to build with doxx is baked right in to the application. You don't need to install or know how to run other applications in order to use it.

Unicode Support

doxx speaks your language. There is full UTF-8 character set support across text templates and the text replacement strings that you use in the templates.

For Project Developers

Simple Templates, Simple Keys

Templates and keys were designed for easy development, reuse, and modification. Templates use double curly brace named text replacement tags. Keys employ YAML tag: value text replacement syntax. Build specs are defined in YAML sections at the head of the key and template files. The build files were designed to be legible, easy to develop, and easy to maintain.

Development That Includes Everyone

Project contributions can come from anyone who understands the domain of the project files. With a legible build file format that requires no scripting know-how, content experts can participate in development as easily as those with technical expertise.

Local & Remote Template File Support

doxx builds from local or remote project templates. Host template files or a tar.gz/zip archive of your entire project anywhere that is accessible by GET request and any doxx user can build with it. There are no external application dependencies for your project users and the build experience on the user side looks the same irrespective of your deployment approach.

Broad Build Support

If it's made with text, it should work:

agreements, AppleScript, articles, Awk, .bashrc, batch files, bibliographies, blog posts, Bootstrap projects, business documents, C, C++, C#, Clojure, CoffeeScript, comma delimited data, configuration files, CSS, Cython, Elixir, email, Erlang, Flex, Foundation projects, frameworks, Go, grocery lists, guitar tablature, Gulp projects, Grunt projects, Haskell, HTML, Java, JavaScript, Jekyll projects, JSON, labels, LaTeX, leases, legal documents, LESS, letters, licenses, lists, Lua, makefiles, Markdown, memoranda, novel framework, Objective-C, Octopress projects, Pelican projects, Perl, PHP, plain text files, Python, R, receipts, reports, reStructured Text, RSS, resumes, Ruby, sales documents, SASS, shell scripts, SQL, static web sites, Swift, Stata scripts, tab delimited data, templates, Visual BASIC, WordPress projects, XML, ...

Sharing is Easy

Provide users with the URL to the templates or project archive (a tar.gz or zip compressed archive of the entire project) in a key file stub that includes the available text replacement tags. Users add their text replacement strings to the distributed key file and build their own version of the project locally with the command doxx build.

Batteries are Included

Users do not need to understand, install, or use other command line utilities to build projects with doxx. The routines of common command line system utilities, including those that perform remote file pulls and decompression/unpacking of tar.gz or zip archives, are included in the doxx command set. doxx was developed with Python and, with the exception of the widely available Python interpreter, there are no external application dependencies for your project consumers.

Unicode Support

doxx provides multi-lingual support across build files. The UTF-8 character set supported in template text, template replacement tag names, and the replacement strings that users enter in their key files.

Distribute Binary Files in Your Projects

doxx supports the distribution of images, audio files, video files, pdf files, and any other binary file format with your project. It renders new text files around these binaries (with text replacements if defined in your templates) according to your build specifications.

Learn More

You can learn more about project builds from the Package Repository or third party project releases in the User Quickstart Guide. If you'd like to learn how to develop and distribute your own projects, the Developer Quickstart Guide provides an overview with links to other parts of the documentation.

Detailed documentation of key files, template files, project archives, and application usage is available in the usage section of the documentation.

full of hot air doxx Example

Here is a very simple doxx project example to give you a flavor of the doxx approach to text templating and project builds.

Project Layout

A doxx project includes a key file and one or more template files. In this simple, single template project example, the key and template files are both located in the same directory:

├── project-directory
	├── key.yaml      # the doxx key file
    └── letter.doxt   # the doxx template file

doxx Template

doxx templates include a YAML build specification header followed by the template text.

The delimiters {{ and }} are used to indicate the named text replacement positions in the template:


extension: txt
destination_directory: build

Hello {{to}},

I am a big fan of doxx.


doxx Key

doxx keys include two YAML formatted sections. The top section includes the path (relative to the key file) to one or more templates. The bottom section includes the key to the text replacements in these templates.


template: letter.doxt


to: Chris
from: me

doxx keys can be mapped to templates in a one-to-one (with a template setting as shown above) or one-to-many (with a templates setting) fashion. They can also be used with a project archive file that contains an entire project directory structure (with a project setting). Project archives can include multiple templates and other file types (including images, pdf files, audio files, and other binary file types). More information is available in the key file documentation.

Build Command

To build your file, enter:

$ doxx build

Your key.yaml file is automatically detected in the current working directory and the file is rendered.


Your rendered file:

Hello Chris,

I am a big fan of doxx.


Post-Build Directory Layout

Because the build destination directory was specified in your template file, the rendered text file is written to the build sub-directory using a concatenation of the base filename of the template and the extension that you specified in the template extension field as the rendered file path (build + letter + .txt):

├── project-directory
	├── key.yaml         # the doxx key file
    ├── letter.doxt      # the doxx template file
	└── build
		└── letter.txt   # the rendered text file

You can modify the rendered file name by adding a basename field to the template build specification section. The build directory can be changed by altering the destination_directory build spec field. Detailed instructions are available in the template file documentation.

More complex multi-file build project architecture is possible and simple to design. The template documentation and project archive documentation demonstrate how to create projects with multiple templates and include binary files in your build. The key file documentation provides instructions on how to use the templates and project build spec fields to generate these projects with doxx build.

going deep Learn More

Want to learn more? The Usage documentation provides details on command line syntax, available commands, and appropriate use. Head to the Syntax section to get started.

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