The following guide provides an overview of how to build new projects with doxx. It will cover how to find and build commonly used project types that are maintained in the doxx Package Repository, and how to build projects that are released by other developers. You will learn about the files that are used to perform the build process and should understand how to modify and use these files by the end of this Guide. For more detailed information, please follow the links throughout the Guide.
I recommend that you install doxx so that you can follow along with the examples. Instructions are on the Install page.
Let's dive in.
The doxx Package Repository User Workflow
Search for a Package
doxx search [search term]
Learn About the Project Package
doxx whatis [package name]
Pull the Package Key
doxx pullkey [package name]
Build the Project
I Want to Create Project X, How Do I Start?
As a demonstration of a Package Repository project, let's assume that you are interested in developing a new HTML5 website with the Zurb Foundation framework.
Search the Package Repository
You can start by checking to see if the project is available in the doxx Package Repository. To perform a search, use the
doxx search command (docs).
doxx search attempts to match your search query to appropriate Package Repository projects using a fuzzy search algorithm. Enter any keyword or project name as your search term and include quotes around multi-word searches.
Give it a try. Launch your terminal application and enter the command:
$ doxx search foundation
doxx searches the repositories and displays the Foundation package result:
If you prefer the web browser to the command line, head to the Package Repository on GitHub and use the search box at the top of the page to locate packages.
When you identify a package of interest, you can get the project description with the
$ doxx whatis framework-html-zurb-foundation [*] doxx: Looking up the package description... Package: framework-html-zurb-foundation Description: Zurb Foundation 5 HTML framework
How To Tell doxx What To Do
Now that you've identified a package that you'd like to build, let's get to it. In order to understand doxx builds, you need to understand the
key.yaml file, otherwise known as the project key file (docs).
Project Key Files
Every doxx project includes a key file that acts as command central for the project build. As a project user, your job is to place the
key.yaml file in the root directory of your new project, then define how your build should be customized by entering additional data into this file.
Project Key Structure
A key file is split into two sections that are divided by triple dash
--- delimiters. The top section, which we will call the build specification section, tells doxx how to build your project from template files or project archive files (i.e. tar.gz or zip archives of the entire project). The bottom section, which we will call the string replacement definition section, includes a list of text replacement sites in the project templates. These are text replacement tag names that correspond to the same tags in the template files. They are there so that you can define the text customizations that you want to include in the files generated from project templates.
Pull a Package Repository Project Key File
So how do we get a key file from the Package Repository into the local new project directory? doxx provides the
pullkey command to take care of this. This command pulls the remote key file to your current working directory. It will arrive with the filename
key.yaml no matter what package you are building.
Let's pull the Foundation package key. Enter the package name after the
pullkey command like this:
$ doxx pullkey framework-html-zurb-foundation
And then open the
key.yaml file in a text editor. The key file for the Foundation package at the time of this writing looks like this:
--- project: "https://github.com/doxx-repo/framework-html-zurb-foundation/releases/download/current/framework-html-zurb-foundation.tar.gz" --- ################################ # index.html replacements # template: templates/index.doxt ################################ # Enter a title for your index.html page title: # jQuery v2.1.3 # Change the path in the next line if you intend to use a different jQuery script jquery: js/vendor/jquery.js # Modernizr v2.8.3 # Change the path in the next line if you intend to use a different Modernizr script modernizr: js/vendor/modernizr.js # Include normalize.css in your project? # Uncomment the next line to include normalize.css in your project # normalize: "<link rel='stylesheet' href='css/normalize.css' />" # Remove or comment out (with #) the next line if you included normalize.css in your # project with the above normalize: definition normalize:
I color coded the sections of the file to point out the structure that we discussed above.
The Build Specification Header Section
The green section at the top enclosed between
--- delimiters is the build specification header section. There's no need to modify this information. It points to the package tar.gz archive file for the project that you are about to build.
The String Replacement Definition Section
The string replacement definition section is where you get involved in your project build. Every project will have its own set of possible replacement string keys that correspond to text replacement sites in the template files. For the Foundation project, these are the purple colored
The comments above the keys describe the key positions in the project files. In your text editor, enter a title for your
index.html page to the right of the
title: key. You can include quotes around the title but they aren't necessary in most cases. Your text entries in this section of the key file follows YAML formatting rules. If you find that you are running into key file parsing errors, try to wrap the offending strings in quotes.
modernizr: keys include the Foundation project defaults for the current release. If you wanted to change the version of one of these scripts, you would modify the file path associated with the respective key and include the file in your project after your build. There is no need to change these definitions in this example.
Lastly, have a look at the
normalize: key. If you execute a build with any key undefined (i.e. nothing entered after the colon), the replacement tag in the template file is simply erased. The instructions indicate that you should uncomment (this means remove the # symbol in front of) the
normalize: key that includes a stylesheet definition if you would like to include it and simply leave the default blank definition if you do not. Keys should be unique so if you uncomment the
normalize: key that defines the file, you should either delete or comment out (this means add a # symbol at the beginning of the line) the other
Save your file and let's build!
The build command is:
$ doxx build
Enter this in the root of your new project directory where your
key.yaml file is located. That's it. After some clanking and a few sparks, doxx indicates that the job is done.
The Rendered Project
Open your project directory and have a look at what you created. Immediately following the build, the project looks like this:
├── css │ ├── foundation.css │ ├── foundation.min.css │ └── normalize.css ├── humans.txt ├── img ├── index.html ├── js │ ├── foundation │ │ ├── foundation.abide.js │ │ ├── foundation.accordion.js │ │ ├── foundation.alert.js │ │ ├── foundation.clearing.js │ │ ├── foundation.dropdown.js │ │ ├── foundation.equalizer.js │ │ ├── foundation.interchange.js │ │ ├── foundation.joyride.js │ │ ├── foundation.js │ │ ├── foundation.magellan.js │ │ ├── foundation.offcanvas.js │ │ ├── foundation.orbit.js │ │ ├── foundation.reveal.js │ │ ├── foundation.slider.js │ │ ├── foundation.tab.js │ │ ├── foundation.tooltip.js │ │ └── foundation.topbar.js │ ├── foundation.min.js │ └── vendor │ ├── fastclick.js │ ├── jquery.cookie.js │ ├── jquery.js │ ├── modernizr.js │ └── placeholder.js ├── key.yaml ├── pkey.yaml ├── project.yaml ├── robots.txt └── templates └── index.doxt
Foundation didn't provide all of those .yaml and .doxt files (the green ones). doxx is to blame. You don't need all of that cruft. Let's tidy things up so that you can get to work on your new site.
doxx build files and the unnecessary templates directory are removed from the project with the command:
$ doxx clean
Poof! Your very own binary maid. Now you have a Foundation project with a directory structure that looks exactly as the Foundation folks intended:
├── css │ ├── foundation.css │ ├── foundation.min.css │ └── normalize.css ├── humans.txt ├── img ├── index.html ├── js │ ├── foundation │ │ ├── foundation.abide.js │ │ ├── foundation.accordion.js │ │ ├── foundation.alert.js │ │ ├── foundation.clearing.js │ │ ├── foundation.dropdown.js │ │ ├── foundation.equalizer.js │ │ ├── foundation.interchange.js │ │ ├── foundation.joyride.js │ │ ├── foundation.js │ │ ├── foundation.magellan.js │ │ ├── foundation.offcanvas.js │ │ ├── foundation.orbit.js │ │ ├── foundation.reveal.js │ │ ├── foundation.slider.js │ │ ├── foundation.tab.js │ │ ├── foundation.tooltip.js │ │ └── foundation.topbar.js │ ├── foundation.min.js │ └── vendor │ ├── fastclick.js │ ├── jquery.cookie.js │ ├── jquery.js │ ├── modernizr.js │ └── placeholder.js └── robots.txt
Examine Your Text Replacements
index.html file and have a look at the text replacements that doxx performed for you. If you entered a definition for the
title: key, it can now be found between the
normalize: replacement tag was located. If you would have decided to include the normalize.css file in your project, this is where your stylesheet definition would have been located.
That's a Wrap (for the Package Repository)
That's a doxx build from a Package Repository project in a nutshell. OK so it was a big nutshell, but you now know how to
doxx pullkey, complete a key file,
doxx build, and
doxx clean. You can use this workflow for any project in the repository.
I'll pass along one additional nugget that will prove useful as you work with the Package Repository. You'll inevitably want to have a look at the template files for some projects before you build so that you can understand the text replacement sites, or modify them to meet the customization needs of your project.
doxx pull (note that this differs from the
pullkey command) will pull the entire project to your current working directory so that you can review templated and non-templated text files, any associated binary files, and the key file before you build.
The syntax for the command is:
$ doxx pull [Package Repository project name]
To use it for this Foundation project, the command is:
$ doxx pull framework-html-zurb-foundation
Workflow for Builds from Third Party Templates and Project Archives
doxx provides developers with the flexibility to create projects that build from local or remote template files and local or remote project archives. In order to support this range of build types and potential build file locations, the workflow for third party projects differs slightly from that used for official releases in the Package Repository.
The first step for project users is always to generate a local key file in the top level of your new project directory. The build specification section of this file needs to define the source of the template or project archive files with either local file paths or URLs. If you are designing the key file yourself, please review the key file documentation for additional information.
Ideally, the project developer will provide a key file stub that includes the appropriate file paths or URLs and any available text replacement tags that are included in the project templates. In order to obtain this key file, you can use the following approaches:
Workflow for Builds from Local Third Party Templates + Key Files
If a developer asks you to download the key and template files, you will have a complete local doxx project and can build from local filepaths. Complete your text replacements in the
key.yaml key file, then enter the command:
Build the Project
Workflow for Builds from Remote Third Party Templates + Key Files
Pull the Key File
doxx pull [key file URL]
Pull the Template File(s)
doxx pull [template file URL]
Build the Project
Workflow for Builds from Local Third Party Project Archives
Unpack Local Project Archive
doxx unpack [tar.gz / zip project archive file path]
Build the Project
Workflow for Builds from Remote Third Party Project Archives
Pull and Unpack Remote Project Archive
doxx pull [tar.gz / zip project archive URL]
Build the Project
Clean the Project Directory Following the Build
After a successful build, scrub the doxx build files from the project by running the following command in the top level directory:
$ doxx clean
Commands That Do Not Work with Third Party Projects
whatis were not designed for use with third party projects. They are commands for the Package Repository. The Syntax page describes all doxx commands for future reference.
So You've Got the Itch?
Working with premade projects just aren't cutting it or you can't find the project that you need? The Quickstart Guide for Developers is a good place to get started designing your own. It goes into additional detail about key and template file formats and how to package your projects for distribution. It's littered with links to the rest of the documentation and will get you up and running in no time.