README

== developers.yubico.com

The developers.yubico.com site is generated from the content located in the
content subdirectory. Directories form the site hierarchy and AsciiDoc files
form the content.

The hierarchy consists of multiple levels of directories in the "content" root.
Filenames are case-sensitive and should be both readable and URL safe
(underscores will be converted into spaces when displayed in the menu
structure).

Different modules can be added to extend functionality, such as generating a
releases page from a template and a file listing, or creating a whole
subsection from a GitHub projects README and documentation pages.

=== Environment variables
OFFLINE:: Skip all network updates.
NOPROJECTS:: Do not build software projects (useful to get a shorter test cycle).
NORELEASES:: Do not build release pages (avoids pulling the huge binaries repo)

=== Building
The website is built using Docker. The following command will compile a static
website in `htdocs/dist/` directory.

 make build

=== Running locally
Once built, the following command will serve `htdocs/dist/` directory on
http://localhost:8080

 make httpd

=== Building fast and locally for local development
For faster local development for document, use the following command.  This will run with both
NOPROJECTS = true and NORLEASES = true

 make build_noprojects httpd

=== Web dependencies
We use bower to manage js/css dependencies for the site. Bower is only needed
when changing/updating the dependencies as the dependency artifacts are checked
in to the repository.

To make modifications, modify the bower.json file and run "bower install", then
add all files from static/vendor to the repository.

=== Context
A context object provides information about the current state. It provides:
* Base source directory
* Base target directory
* Relative current source directory
* Relative current target directory

=== Modules
Modules can be used to modify content in Subsections, like converting AsciiDoc
files to HTML, or pulling content from an external source such as GitHub. Each
module gets invoked with a source Subsection directory, as well as the output
directory. A module is used to decorate partials with surrounding content.

Which modules to use is defined by the configuration in settings.json
Module configuration is done on a per-directory level in a .conf.json file in
each directory.

For information on the individual modules, see comments in the source code in
the devyco/modules/ directory.