doxx Quickstart Guide for Project Users

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

doxx build

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:

framework-html-zurb-foundation

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 whatis command:

$ 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 title:, jquery:, modernizr:, and normalize: keys.

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.

The jquery: and 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 normalize: key.

Save your file and let's build!

Build Time

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.

Cleaning House

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

Open the 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 <title> and </title> tags in the head section of your html. Though we didn't change them in this example, the jQuery and Modernizr javascript file paths were text replacement tags in the template file. You'll also notice that there is an empty line in the head section where 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 search, doxx whatis, doxx pullkey, complete a key file, doxx build, and doxx clean. You can use this workflow for any project in the repository.

Here are links to the documentation for the search command, whatis command, pullkey command, key files, build command, and clean command if you want to dig a bit deeper.

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

doxx build

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

doxx build

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

doxx build

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

doxx build

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

Note that pullkey, search, and 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.


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