guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [2/2] incubator-guacamole-website git commit: Add and exclude from Jekyll build.
Date Tue, 26 Apr 2016 19:57:02 GMT
Add and exclude from Jekyll build.


Branch: refs/heads/master
Commit: c47a2e19a6b779a54240ed37df9032c31ac39630
Parents: 30834f4
Author: Michael Jumper <>
Authored: Tue Apr 26 12:56:46 2016 -0700
Committer: Michael Jumper <>
Committed: Tue Apr 26 12:56:46 2016 -0700

----------------------------------------------------------------------   | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 _config.yml |   1 +
 2 files changed, 150 insertions(+)
diff --git a/ b/
new file mode 100644
index 0000000..1b53acd
--- /dev/null
+++ b/
@@ -0,0 +1,149 @@
+The Apache Guacamole website
+This repository contains the source for the website of Apache Guacamole, a
+clientless remote desktop solution currently undergoing incubation at the
+Apache Incubator.
+The website itself is completely static, being automatically generated by
+[Jekyll]( prior to deployment. The content of the website
+is written in a mixture of HTML and Markdown, with dynamic portions written
+using [liquid templating]( Templated
+content is interpreted only a build time, with the final result being
+completely static.
+To facilitate ease of development and testing, this repository also contains a
+build script, ``, the usage of which is documented below.
+Table of contents
+* [Repository structure](#repository-structure)
+* [Build prerequisites](#build-prerequisites)
+* [Testing changes locally](#testing-changes-locally)
+* [Publishing changes](#publishing-changes)
+Repository structure
+In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-
+licensed project, the repository contains the following critical files:
+| Filename      | Description
+| ------------- | -----------
+| `_config.yml` | Configuration information controlling the Jekyll build.  This is a standard
Jekyll file. See: [Jekyll directory structure](
+| ``    | The website build script (usage documented below).
+| `doc/`        | Per-release documentation for Apache Guacamole. This directory contains
one subdirectory per release, where each subdirectory contains the overall manual (`.../gug/`)
API documentation for each part of the Guacamole core (`.../libguac/`, `.../guacamole-common/`,
etc.). Files in this directory are not interpreted by Jekyll, as there are far too many files
for this to be reasonable. They are instead copied into place by the `` script.
+| `images/`     | Images which are referenced within the website HTML and CSS.
+| `pub/`        | Miscellaneous public files, such as test scripts. The test scripts in this
directory have historically been shared to users to help with debugging.
+| `styles/`     | All CSS files referenced by the website HTML.
+| `_includes/`  | Common HTML fragments used by Jekyll and referenced in other templates,
such as the website header and footer. These *must* be HTML only. This is a standard Jekyll
directory. See: [Jekyll directory structure](
+| `_layouts/`   | Templates describing the structure of different types of content. This
is a standard Jekyll directory. See: [Jekyll directory structure](
+| `_links/`     | Documents which contain metadata describing the links which should appear
in the site navigation menu. The documents here are completely empty except for the metadata.
+| `_releases`   | Release notes for Guacamole releases, including metadata describing the
files and documentation associated with those releases.
+Build prerequisites
+The build depends entirely on Jekyll, thus this must be installed first. If you
+do not yet have Jekyll installed, please see [Jekyll's own installation
+instructions]( to get started.
+Beyond Jekyll, you will also need:
+* A POSIX-compliant implementation of `sh` (to run ``)
+* git (to clone this repository and to publish changes)
+* `mktemp` (used by `` when staging changes prior to publishing)
+The `` script will check whether the required programs are installed,
+and will fail early with an appropriate message if a required program cannot be
+The build script handles three primary variations of common build tasks:
+1. The build itself, when invoked as `./`. This invokes Jekyll and recursively copies
the `doc/` (part of the website source) and `_site/` (generated by Jekyll during the build)
to the `content/` directory.
+2. Serving a local copy of the website, when invoked as `./ PORT`.
+3. Staging local changes for commit to the special "asf-git" branch, when invoked as `./
stage`. Once changes are committed and pushed to "asf-git", the public website will be updated
by the ASF's gitpubsub.
+Testing changes locally
+To test your changes to the website, you can either invoke `./` to build a static
copy of the site to the `content/` subdirectory, or invoke `./ PORT` (where `PORT`
a TCP port number) to both build the static copy of the site *and* run Ruby's web server to
serve `content/` locally at the given port:
+    $ ./ 8080
+    Configuration file: /home/mjumper/apache-guacamole/incubator-guacamole-website/_config.yml
+                Source: /home/mjumper/apache-guacamole/incubator-guacamole-website
+           Destination: /home/mjumper/apache-guacamole/incubator-guacamole-website/_site
+     Incremental build: disabled. Enable with --incremental
+          Generating...
+                        done in 0.563 seconds.
+     Auto-regeneration: disabled. Use --watch to enable.
+    Copying "doc/" and built site to "content/" ...
+    Done. Full site is now within the "content/" directory.
+    [2016-04-26 12:35:36] INFO  WEBrick 1.3.1
+    [2016-04-26 12:35:36] INFO  ruby 2.1.7 (2015-08-18) [x86_64-linux]
+    [2016-04-26 12:35:36] INFO  WEBrick::HTTPServer#start: pid=18927 port=8080
+When done testing your local changes, press `Ctrl`&nbsp;+&nbsp;`C` to stop the
+web server and return to the shell.
+Publishing changes
+Changes to the website are published using Apache's
+which relies on a special branch called "asf-git" containing *all website
+content* within a directory called `content/`.
+In the Apache Guacamole website repository, the "asf-git" branch is an "orphan"
+branch. The branch has no commits in common with the "master" branch and
+consists solely of the `content/` subdirectory. Updating the website thus
+1. Making and testing your changes locally
+2. Replacing the entire contents of the `content/` directory within "asf-git"
+   with the newly-generated `content/` directory.
+The `` script can take care of all this for you when invoked as
+`./ stage`:
+    $ ./ stage
+    Configuration file: /home/mjumper/apache-guacamole/incubator-guacamole-website/_config.yml
+                Source: /home/mjumper/apache-guacamole/incubator-guacamole-website
+           Destination: /home/mjumper/apache-guacamole/incubator-guacamole-website/_site
+     Incremental build: disabled. Enable with --incremental
+          Generating...
+                        done in 0.568 seconds.
+     Auto-regeneration: disabled. Use --watch to enable.
+    Copying "doc/" and built site to "content/" ...
+    Done. Full site is now within the "content/" directory.
+    Switched to branch 'asf-git'
+    Removing
+    Removing _site/
+    Content staged for commit. Use git to commit the results when ready.
+    NOTE: The script will no longer exist. To serve the staged
+    contents, run:
+        ruby -run -e httpd content/ -p PORT
+    where PORT is the port number where the HTTP server should listen.
+    $
+At this point, you will be on the "asf-git" branch and the current directory
+will contain only the `content/` subdirectory:
+    $ ls
+    content
+    $
+Keep in mind that the new content is only *staged* for commit. It has not yet
+been committed. Once you have verified that the staged content is as expected,
+commit your changes (along with a useful commit message describing the changes
+at a high level) using `git commit` and publish the update using
+`git push origin`.
+If you wish to unstage your changes, use `git reset --hard HEAD` to return to
+the original state of "asf-git", wiping out any local modifications made by
+``. You can then return to whichever branch you were working on with
+`git checkout`.
diff --git a/_config.yml b/_config.yml
index 1c66f79..c21c2d0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -23,6 +23,7 @@ title: Apache Guacamole
 # Build settings
 markdown: kramdown
+    -
     - content
     - doc

View raw message