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.