brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [10/11] incubator-brooklyn git commit: wholesale copy of master docs (from #458) with version changed to 0.7.0-M2-incubating
Date Tue, 20 Jan 2015 16:37:27 GMT
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_layouts/guide-base.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/guide-base.html b/docs/_layouts/guide-base.html
deleted file mode 100644
index 3facdb6..0000000
--- a/docs/_layouts/guide-base.html
+++ /dev/null
@@ -1,183 +0,0 @@
----
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements.  See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-# 
-#  http://www.apache.org/licenses/LICENSE-2.0
-# 
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-layout: base
----
-
-<head>
-
-  {% include base-head.html %}
-
-  <link rel="stylesheet" href="{{ site.path.style }}/css/guide.css" type="text/css" media="screen" />
-  <link rel="stylesheet" href="{{ site.path.style }}/css/guide-toc.css" type="text/css" media="screen" />
-
-    <script type="text/javascript" src="https://www.google.com/jsapi"></script>
-  
-	<!-- Sidebar/ToC Scripts and CSS -->
-	<script src="{{ site.path.style }}/deps/jquery-ui/jquery-ui-1.8.18.custom.min.js"></script>
-	<link rel="stylesheet" type="text/css" href="{{ site.path.style }}/deps/jquery-ui/jquery-ui-1.8.18.custom.css" />
-	
-	<script type="text/javascript" src="{{ site.path.style }}/deps/superfish.js"></script>
-	<script type="text/javascript" src="{{ site.path.style }}/deps/jquery.cookie.js"></script>
-	
-<!-- Clipboard support -->
-<script src="//cdnjs.cloudflare.com/ajax/libs/zeroclipboard/1.3.1/ZeroClipboard.min.js"></script>
-<style type="text/css">
-.clipboard_container { float: right; padding: 8px; }
-.clipboard_button {
-    background-image: url("{{ site.path.style }}/img/clipboard-green-normal.png");
-    background-size: 18px 21px;
-    width: 18px; height: 21px;
-    overflow: auto;
-}
-.clipboard_button:hover, .clipboard_button.zeroclipboard-is-hover { background-image: url("{{ site.path.style }}/img/clipboard-green-hover.png"); }
-.clipboard_button:active, .clipboard_button.zeroclipboard-is-active { background-image: url("{{ site.path.style }}/img/clipboard-green-click.png"); }'
-</style>
-<script type="text/javascript"> <!-- clipboard -->
-  ZeroClipboard.config({ moviePath: '//cdnjs.cloudflare.com/ajax/libs/zeroclipboard/1.3.1/ZeroClipboard.swf' });
-</script>
-<script type="text/javascript"> <!-- clipboard positioning -->
-$(document).ready(function() {
-  $('<div class="clipboard_container" title="Copy to Clipboard">'+
-    '<div class="clipboard_button"/>'+
-  '</div>').insertBefore($('div.highlight'))
-  $('div.clipboard_container').each(function(index) {
-    var clipboard = new ZeroClipboard();
-    clipboard.clip( $(this).find(":first")[0], $(this)[0] );
-    var target = $(this).next();
-    var txt = target.text().trim();
-    if (target.find('code.bash')) {
-      // Strip out bash prompts from the start of each line (i.e. '$' or '%' characters
-      // at the very start, or immediately following any newline). Correctly handles continuation
-      // lines, where a leading '$' or '%' is *not* a prompt character.
-      txt = txt.replace(/(^|[^\\]\n)[$%] /g, "$1");
-    }
-    clipboard.on( 'dataRequested', function (client, args) {
-      client.setText( txt );
-    });
-  });
-});
-</script>
-
-    <script type="text/javascript">
-        // initialise menu delay
-        $(document).ready(function() {
-              $('ul#mainmenu').superfish({ 
-                autoArrows:  false,  // disable generation of arrow mark-up 
-                dropShadows: false,  // disable drop shadows 
-                disableHI:   true,   // set to true to disable hoverIntent detection 
-                delay:       500,    // the delay in milliseconds that the mouse can remain outside a submenu without it closing 
-                speed:       'fast', 
-            });
-        });
-    </script>
-
-<script type="text/javascript">
-
-<!-- search -->
-	$(function() {
-		$('#simple_google')
-			.submit(function() {
-				$('input[name="q"]').val("site:" + document.location.hostname + " " + $('input[name="brooklyn-search"]').val());
-			return true;
-			});
-		$('input[name="brooklyn-search"]').focus(function() {
-				if ($(this).val() === $(this).attr('placeholder')) {
-					$(this).val('');
-				}
-			})
-			.blur(function() {
-				if ($(this).val() === '') {
-					$(this).val($(this).attr('placeholder'));
-				}
-			})
-			.blur();
-    });
-    
-<!-- page notes -->
-   	$(function() {
-		if (document.location.pathname.replace(/^\/([^\/]*).*$/, '$1') === "v"){
-			var thisversion = document.location.pathname.split("/")[2],
-				msg = "";
-			
-			if (thisversion != 'latest' && !$.cookie('brooklyn_versions') || 
-			        (($.inArray('ALL', $.cookie('brooklyn_versions').split(",")) === -1) &&
-			        ($.inArray(thisversion, $.cookie('brooklyn_versions').split(",")) === -1)) ){
-			    msg += "<div class='warning_banner_image'><img src='{{ site.path.style }}/img/warning.png'/></div>";
-				msg += "<p>This content is for <strong>Brooklyn "+thisversion+"</strong>, and may differ across versions.</p>";
-			    msg += "<p>Are you using version "+thisversion+"?</p>";
-				msg += "<p class='warning_banner_buttons'>";
-				msg += "<a href = '#' onclick=\"set_user_version('"+thisversion+"');\">Yes, hide this warning</a>";
-			    msg += "<a href = '{{ site.page.guide }}'>No, show me the latest version</a>";
-				msg += "<a href = '{{ site.page.guide }}/meta/versions.html'>Show all versions</a>";
-				msg += "</p>"
-							
-				$('#page_notes').html(msg);
-				$('#page_notes').fadeIn('slow');
-			}
-		}
-	});
-   	function get_user_versions() {
-   	    return $.cookie("brooklyn_versions") ? $.cookie("brooklyn_versions").split(",") : [];
-   	};
-	function set_user_version(version) {
-		var version_cookie = get_user_versions();
-		version_cookie.push(version);
-		$.cookie('brooklyn_versions', version_cookie, { expires: 365, path: '/' });
-		$('#page_notes').fadeOut();
-		event.preventDefault ? event.preventDefault() : event.returnValue = false;
-	};
-    function set_user_versions_all() {
-        var version_cookie = get_user_versions();
-        version_cookie.push("ALL");
-        $.cookie('brooklyn_versions', version_cookie, { expires: 365, path: '/' });
-        $('#page_notes').fadeOut();
-        event.preventDefault ? event.preventDefault() : event.returnValue = false;
-    };
-    function clear_user_versions() {
-        $.removeCookie('brooklyn_versions', { path: '/' });
-        $('#page_notes').fadeIn('slow');
-        event.preventDefault ? event.preventDefault() : event.returnValue = false;
-    };
-	
-   
- <!-- analytics -->
-	var _gaq = _gaq || [];
-	_gaq.push(['_setAccount', 'UA-30530918-1']);
-	_gaq.push(['_trackPageview']);
-	
-	(function() {
-	  var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-	  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-	  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
-	})();
-</script>
-
-</head>
-
-<body>
-
-    <ul id="shortcuts" title="Accessibility shortcuts menu">
-        <li><a href="#maincontent">Skip to main content</a></li>
-    </ul>
-   
-
-{{ content }}
-
-
-</body>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_layouts/guide-normal.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/guide-normal.html b/docs/_layouts/guide-normal.html
deleted file mode 100644
index 67278e7..0000000
--- a/docs/_layouts/guide-normal.html
+++ /dev/null
@@ -1,23 +0,0 @@
----
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements.  See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-# 
-#  http://www.apache.org/licenses/LICENSE-2.0
-# 
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-layout: website-normal
----
-
-{{ content }}
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_layouts/guide-old.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/guide-old.html b/docs/_layouts/guide-old.html
deleted file mode 100644
index 736c838..0000000
--- a/docs/_layouts/guide-old.html
+++ /dev/null
@@ -1,65 +0,0 @@
----
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements.  See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-# 
-#  http://www.apache.org/licenses/LICENSE-2.0
-# 
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-layout: guide-base
----
-
-{% include topmenu.html %}
-
-<div id="container">
-
-    <div id="header">
-
-        <div id="menubar">  
-
-{% include topbar.html %}                    
-
-            <form method="get" id="simple_google" class="searchform" action="http://www.google.com/search" method="get">
-                <input type="text" class="searchinput" name="brooklyn-search" placeholder=" Search: type &amp; hit enter" />
-                <input type="hidden" name="q" value="" />
-            </form>
-            
-        </div>
-                
-    </div><!--header-->
-    
-    <div id="contentcontainer">
-    
-        <div id="maincontent">
-
-{% include breadcrumbs.html %}
-
-<div id="page_notes"></div>
-
-<h1 id="header_title">{{ page.title }}</h1>
-    
-{{ content }}
-
-        </div><!--maincontent-->
-        
-      <div id="sidebar">
-      
-{% include sidebar.html %}
-
-      </div>
-
-    </div><!--contentcontainer-->
-
-</div><!--container-->
-
-{% include footer.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_layouts/website-landing.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/website-landing.html b/docs/_layouts/website-landing.html
index a3ae36a..7c1bb8b 100644
--- a/docs/_layouts/website-landing.html
+++ b/docs/_layouts/website-landing.html
@@ -32,14 +32,17 @@ layout: website-base
                 infrastructure, communications, and decision making process have stabilized in a manner consistent with other
                 successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of
                 the code, it does indicate that the project has yet to be fully endorsed by the ASF.
+                <p>
                 Apache Brooklyn is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License v2.0</a>.
             </div>
             <div class="col-md-3">
                 <p><img src="https://incubator.apache.org/images/egg-logo.png" alt="Apache Incubator" /></p>
                 <p>
-                    <a class="btn btn-sm btn-default" href="https://github.com/apache/incubator-brooklyn/edit/master/docs/{{ page.path }}">Edit This Page</a>
-                    <br />
-                    <a href="https://brooklyn.incubator.apache.org/community/how-to-contribute-docs.html">help with editing</a>
+                <a class="btn btn-sm btn-default" href="https://github.com/apache/incubator-brooklyn/edit/master/docs/{{ page.path }}">Edit This Page</a>
+                <a href="{{ site.url_root }}{{ site.path.website }}/community/how-to-contribute-docs.html"
+                    data-toggle="tooltip" data-placement="top" title="How to Edit Documentation" data-delay="400"/>
+                  <span class="octicon octicon-question octicon-footer"></span>
+                </a>
                 </p>
             </div>
         </div>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_layouts/website-normal.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/website-normal.html b/docs/_layouts/website-normal.html
index ba6e9b8..a89bb91 100644
--- a/docs/_layouts/website-normal.html
+++ b/docs/_layouts/website-normal.html
@@ -22,67 +22,16 @@
 # menu_customizations can be used, including force_inactive to prevent highlighting
 layout: website-base
 ---
-<div class="container">
+<div class="container" id="main_container">
     <div class="row">
-        <div class="col-md-9">
+        <div class="col-md-9" id="content_container">
+            <div id="page_notes"></div>
             <h1>{{ page.title }}</h1>
             {{ content }}
         </div>
-        <div class="col-md-3">
-            <div class="list-group side-menu">
-{% comment %}
-
-  Case 1) If we're the landing page show nothing.
-  Case 2) If we're contained in the top (landing page) menu, show our menu if we have one.
-  Case 3a) Otherwise if we're contained in a menu, show that menu.
-  Case 3b) And if we have a menu, show our menu nested.
-  
-  Note the breadcrumbs are offset:1. This is because usually breadcrumbs include the root;
-  but also if we're overriding breadcrumbs it gives us a way to set a topmenu item (making it breadcrumb[0])
-  while customizing the side menu (make self breadcrumb[1]).
-{% endcomment %}
 
-{% unless page.landing %}
-  {% if page.menu_parent %}
-    {% if page.menu_parent.landing %} {% comment %} case 2 {% endcomment %}
-              {% for item in page.breadcrumb_pages offset:1 %}
-                  <h4 class="{% if forloop.index0 > 0 %} with_preceding{% endif %}{% if forloop.rindex0 > 0 %} with_following{% endif %}">
-                    <a href="{{item.url}}" class="list-group-item{% if item.path == page.menu_path %} active{% endif %} breadcrumb breadcrumb{{ forloop.index0 }}">
-                      {{ item.title_in_menu }}</a></h4>
-              {% endfor %}
-              {% for item in page.menu %}
-                <a href="{{item.url}}" class="list-group-item{% if page.breadcrumbs contains item %} active{% endif %}">{{ item.title_in_menu }}</a>
-              {% endfor %}
-    
-    {% else %} {% comment %} case 3a {% endcomment %}
-              {% for item in page.menu_parent.breadcrumb_pages offset:1 %}
-                  <h4 class="{% if forloop.index0 > 0 %} with_preceding{% endif %}{% if forloop.rindex0 > 0 %} with_following{% endif %}">
-                    <a href="{{item.url}}" class="list-group-item{% if item.path == page.menu_path %}{% unless item.menu_customization.force_inactive %} active{% endunless %}{% endif %} breadcrumb breadcrumb{{ forloop.index0 }}">
-                      {{ item.title_in_menu }}</a></h4>
-              {% endfor %}
-              {% for item in page.menu_parent.menu %}
-                {% if (page.breadcrumb_paths contains item.menu_path) and page.menu %}
-                  {% comment %} case 3b {% endcomment %}
-                  <a href="{{item.url}}" class="list-group-item active with-sub-item">{{ item.title_in_menu }}</a>
-                  <div class="sub-item">
-                   {% for item2 in page.menu %}
-                    <a href="{{item2.url}}" class="list-group-item sub-item">
-                      {{ item2.title_in_menu }}</a>
-                   {% endfor %}
-                  </div>
-                {% else %}
-                  {% comment %} case 3a side menu item {% endcomment %}
-                  <a href="{{item.url}}" class="list-group-item{% if page.breadcrumb_paths contains item.menu_path %}{% unless item.menu_customization.force_inactive %} active{% endunless %}{% endif %}">{{ item.title_in_menu }}</a>
-                {% endif %}
-              {% endfor %}
-        
-    {% endif %}    
-  {% elsif page.menu %}
-    <!-- no pages have a menu without being in the top menu, won't come here -->
-  {% endif %}
-{% endunless %}
-        
-            </div>
+        <div class="col-md-3">
+            {% include sidemenu.html %}
         </div>
     </div>
 </div>

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_plugins/brooklyn_jekyll_util.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/brooklyn_jekyll_util.rb b/docs/_plugins/brooklyn_jekyll_util.rb
new file mode 100644
index 0000000..fd3688d
--- /dev/null
+++ b/docs/_plugins/brooklyn_jekyll_util.rb
@@ -0,0 +1,129 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+# useful tags:
+
+# printing
+#     puts message
+#     putv variable_to_print_raw
+#     putp variable_to_pretty_print
+
+# eval and control flow
+#     set_hash_entry hash key variable_to_set  # because sometimes jekyll eval order is different
+#     fail message                             # to fail with a message
+
+# stack manipulation:
+#     push stack x  # pushs x to stack and clears x
+#     pop stack x   # pops from stack into x
+# useful e.g. in recursive include calls where x might overwritten
+
+require 'pp'
+
+module BrooklynJekyllUtil
+  class PutsTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      puts "#{@text}"
+    end
+  end
+  class PutvTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      puts "#{@text}: #{context[@text]}"
+    end
+  end
+  class PutpTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      puts "#{@text}:"
+      PP.pp(context[@text])
+      nil
+    end
+  end
+  
+  class SetHashEntryTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      args = @text.split(/\W+/)
+      raise "Need 3 args, the hash, the key, and the var to set" unless args.length == 3
+#      puts "getting #{args[0]}['#{args[1]}']"
+#      PP.pp(context[args[0]])
+#      PP.pp(context[args[0]][args[1]])
+      
+      context[args[2]] = context[args[0]][args[1]]
+      nil
+    end
+  end
+
+  class FailTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      raise "Fail#{@text.length>0 ? ": #{@text}" : ""}"
+    end
+  end
+  
+  class PushTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      args = @text.split(/\W+/)
+      raise "Need 2 args, the stack and the var" unless args.length == 2
+      context[args[0]] = [] unless context[args[0]]
+      context[args[0]].push(context[args[1]])
+      context[args[1]] = nil
+    end
+  end
+  class PopTag < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      @text = text
+    end
+    def render(context)
+      args = @text.split(/\W+/)
+      raise "Need 2 args, the stack and the var" unless args.length == 2
+      context[args[1]] = context[args[0]].pop();
+      nil
+    end
+  end
+end
+
+Liquid::Template.register_tag('puts', BrooklynJekyllUtil::PutsTag)
+Liquid::Template.register_tag('putv', BrooklynJekyllUtil::PutvTag)
+Liquid::Template.register_tag('putp', BrooklynJekyllUtil::PutpTag)
+Liquid::Template.register_tag('set_hash_entry', BrooklynJekyllUtil::SetHashEntryTag)
+Liquid::Template.register_tag('fail', BrooklynJekyllUtil::FailTag)
+Liquid::Template.register_tag('push', BrooklynJekyllUtil::PushTag)
+Liquid::Template.register_tag('pop', BrooklynJekyllUtil::PopTag)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_plugins/brooklyn_metadata.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/brooklyn_metadata.rb b/docs/_plugins/brooklyn_metadata.rb
index b5fe81d..b6efe1f 100644
--- a/docs/_plugins/brooklyn_metadata.rb
+++ b/docs/_plugins/brooklyn_metadata.rb
@@ -1,10 +1,9 @@
 # Inserts several useful fields that can be referenced using {{ name }} syntax
 #
-# TODO: remove, no need for a plugin i think, this is already set in fields.md
-# (although doing it in ruby might be better!)
+# TODO: move things from fields.md to here
 #
-# site.data.brooklyn.version: brooklyn version, such as 0.7.0-M1
-# site.data.brooklyn.is_snapshot: true if this is a snapshot version, otherwise false
+# site.brooklyn.version: brooklyn version, such as 0.7.0-M1 (taken from brooklyn-version in _config.yml)
+# site.brooklyn.is_snapshot: true if this is a snapshot version, otherwise false
 #
 module BrooklynMetadata
 
@@ -12,6 +11,8 @@ module BrooklynMetadata
 
   class Generator < Jekyll::Generator
     def generate(site)
+      raise "Brooklyn version mismatch" if BrooklynMetadata::BROOKLYN_VERSION != site.config['brooklyn-version']
+
       is_snapshot = BrooklynMetadata::BROOKLYN_VERSION.end_with?('-SNAPSHOT')
       
       if is_snapshot
@@ -55,14 +56,16 @@ module BrooklynMetadata
       
       url_set["git"] = "https://github.com/apache/incubator-brooklyn/tree/#{ git_branch }"
       
-      site.data['brooklyn'] = {
+      site.config['brooklyn'] = {
           "version" => BrooklynMetadata::BROOKLYN_VERSION,
           "is_snapshot" => is_snapshot,
           "url" => url_set
       }
-      
-      # TODO check that "#{ brooklyn['url']['git'] }/core/src/main/java/brooklyn/BrooklynVersion.java"
-      # exists AND contains "versionFromStatic = \"#{ brooklyn['version'] }\""
+
+      # config is preferred of data, because you can write just {{ site.brooklyn.xxx }},
+      # also note {{ site.brooklyn-version }} v {{ site.brooklyn-stable-version }} from _config.yml
+      # but some places referenced site.data.brooklyn (i think these have been remove)
+      site.data['brooklyn'] = site.config['brooklyn']
   
     end
   end

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/_plugins/site_structure.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/site_structure.rb b/docs/_plugins/site_structure.rb
index 7d0303c..fbfeb27 100644
--- a/docs/_plugins/site_structure.rb
+++ b/docs/_plugins/site_structure.rb
@@ -19,19 +19,34 @@
 # * (in addition the entry may *be* the actual page object when the item is a page whose menu is not overridden)
 #
 # To build, set `children` as a list of either strings (the relative or absolute path to the child .md file),
-# or as maps with a `path` or `link` (absolute URL) key, a `title` (optional for `path`, to override the title from the file),
-# and (for `path` only) an optional `menu` block (to override the menu inherited from the `children` records in file),
-# `menu_customization` to set arbitrary data available (e.g. for templates to use when styling),
-# `href_path` to specify that an actual click should send to a different page than was used to produce the menu.
+# or as maps indicating the target, one of:
+# * `path` to a markdownfile
+# * `link` as an URL 
+# * `section` anchored in this file (annotated with `<a name="#section"></a>`)
+# And optionally:
+# * a `title` (required for `link`), to override the title from the file
+# * an optional `menu` block  (for `path` only) to override the menu inherited from the `children` record noted at `path`
+# * `menu_customization` to set arbitrary data available (e.g. for templates to use when styling)
+# * `href_path` (for `path` only) to specify that a click should send to a different page than the path used to produce the menu
 #
 # For instance:
 #
 #children:
 #- child.md
-#- { path: child.md }  # identical to above
-#- { path: child.md, title: "Child with New Name" }  # overriding name
-#- { path: child.md, menu: [ { path: subchild.md, title: "Sub-Child with New Name" } ], href_path: subchild.md }  # custom sub-menu with custom title, and click on main sends to submenu 
+#- { path: child.md }  
+#  # identical to above
+#- { path: subchild.md, title: "Sub Child" }   
+#  # different child, with custom title
+#- { path: subchild.md, href_path: subchild_alt.md }  
+#  # takes title and menu from subchild page, but links to subchild_alt
+#- { path: child.md, menu: [ { path: subchild.md, title: "Sub-Child with New Name" } ] } 
+#  # child, but with custom sub-menu and custom title in there 
 #- { path: child.md, menu: null }  # suppress sub-menu (note `null` not `nil` because this is yaml)
+#  # child again, but suppressing sub-menu (note `null` not `nil` because this is yaml)
+#- { section: Foo }
+#- { section: Bar }
+#  # various sections in *this* doc (to make highlighting work for sections requires
+#  # extra JS responding to scrolls; otherwise the parent page remains highlighted)
 #
 # The menu is automatically generated for all files referenced from the root menu.
 # You can also set `breadcrumbs` as a list of paths in a page to force breadcrumbs, and
@@ -207,17 +222,32 @@ module SiteStructure
         data['page'] = page
         breadcrumb_pages << page
         breadcrumb_paths << page.path
+        
+      elsif (item['section'])
+        puts "setting up #{item} as section" if @@verbose
+        section = item['section']
+        section_cleaned = section.gsub(%r{[^A-Za-z0-9]+}, "-").downcase;
+        section_cleaned.slice!(1) if section_cleaned.start_with?("-")
+        section_cleaned.chomp!("-") # 0..-1) if section_cleaned.end_with?("-")
+        link = (parent ? parent.url : "") + '#' + section_cleaned
+        data = { 'link' => link, 'url' => link, 'section' => section_cleaned, 'section_title' => section }
+        data['title'] = item['title'] if item['title']
+        data['title'] = section unless data['title']
+        # nothing for breadcrumbs
+        data['data'] = data
+        result = data
+        
       elsif (item['link'])
         puts "setting up #{item} as link" if @@verbose
         link = render_liquid(site, parent, item['link'])
-        data = { 'link' => link, 'url' => link }
+        data = { 'link' => link, 'url' => link, 'external' => true }
         data['title'] = item['title'] if item['title']
         breadcrumb_pages << data
         breadcrumb_paths << data['link']
         data['data'] = data
         result = data
       else
-        raise "Link to #{item} in #{parent ? parent.path : nil} must have link or path"
+        raise "Link to #{item} in #{parent ? parent.path : nil} must have path or section or link"
       end
 
       data['menu_customization'] = {}.merge(data['menu_customization'] || {}).merge(item['menu_customization'] || {})

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/advanced-concepts.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/advanced-concepts.md b/docs/guide/concepts/advanced-concepts.md
index 1b36170..13e791d 100644
--- a/docs/guide/concepts/advanced-concepts.md
+++ b/docs/guide/concepts/advanced-concepts.md
@@ -1,6 +1,6 @@
 ---
 title: Advanced Concepts
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/application-parent-membership.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/application-parent-membership.md b/docs/guide/concepts/application-parent-membership.md
index 18f1a54..c2d0ac3 100644
--- a/docs/guide/concepts/application-parent-membership.md
+++ b/docs/guide/concepts/application-parent-membership.md
@@ -1,6 +1,6 @@
 ---
 title: Application, Parent and Membership
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png b/docs/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png
new file mode 100644
index 0000000..c2b48ba
Binary files /dev/null and b/docs/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/brooklyn-flow-websequencediagrams.com.png
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/brooklyn-flow-websequencediagrams.com.png b/docs/guide/concepts/brooklyn-flow-websequencediagrams.com.png
new file mode 100644
index 0000000..78eb5c8
Binary files /dev/null and b/docs/guide/concepts/brooklyn-flow-websequencediagrams.com.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/configuration-sensor-effectors.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/configuration-sensor-effectors.md b/docs/guide/concepts/configuration-sensor-effectors.md
index 47ec72e..72e4e93 100644
--- a/docs/guide/concepts/configuration-sensor-effectors.md
+++ b/docs/guide/concepts/configuration-sensor-effectors.md
@@ -1,6 +1,6 @@
 ---
 title: Configuration, Sensors and Effectors
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/dependent-configuration.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/dependent-configuration.md b/docs/guide/concepts/dependent-configuration.md
index 0ed60ff..1d08e1a 100644
--- a/docs/guide/concepts/dependent-configuration.md
+++ b/docs/guide/concepts/dependent-configuration.md
@@ -1,6 +1,6 @@
 ---
 title: Dependent Configuration
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/entities.md b/docs/guide/concepts/entities.md
index 26981e7..0afeb50 100644
--- a/docs/guide/concepts/entities.md
+++ b/docs/guide/concepts/entities.md
@@ -1,6 +1,6 @@
 ---
 title: Entities
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/execution.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/execution.md b/docs/guide/concepts/execution.md
index 4bb4875..7b81fd0 100644
--- a/docs/guide/concepts/execution.md
+++ b/docs/guide/concepts/execution.md
@@ -1,8 +1,6 @@
 ---
 title: Execution
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
+layout: website-normal
 ---
 
 All processing, whether an effector invocation or a policy cycle, are tracked as ***tasks***. This allows several important capabilities:
@@ -31,6 +29,6 @@ For example, a ``TomcatServer`` may implement start and other effectors using a
 Particularly for sensors, some technologies are used so frequently that they are
 packaged as ***feeds*** which can discover their configuration (including from drivers). These include JMX and HTTP (see ``JmxFeed`` and ``HttpFeed``).
 
-Brooklyn comes with entity implementations for a growing number of commonly used systems, including various web application servers, databases and NoSQL data stores, and messaging systems. See: [Extras]({{site.path.guide}}/use/guide/extras/index.html).
+Brooklyn comes with entity implementations for a growing number of commonly used systems, including various web application servers, databases and NoSQL data stores, and messaging systems.
 
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/lifecycle-managementcontext.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/lifecycle-managementcontext.md b/docs/guide/concepts/lifecycle-managementcontext.md
index 3495e17..90cedcf 100644
--- a/docs/guide/concepts/lifecycle-managementcontext.md
+++ b/docs/guide/concepts/lifecycle-managementcontext.md
@@ -1,6 +1,6 @@
 ---
 title: Lifecycle and ManagementContext
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---
@@ -16,7 +16,7 @@ An application entity (``Application`` class) is responsible for starting the de
 An ``Application``'s ``start()`` method begins provisioning the child entities of the application (and their entities, recursively). 
 
 Provisioning of entities typically happens in parallel automatically,
-although this can be customized. This is implemented as ***tasks*** which are tracked by the management plane and is visible in the [web-based management console]({{site.path.guide}}/use/guide/management/index.html#console).
+although this can be customized. This is implemented as ***tasks*** which are tracked by the management plane and is accessible in the web-based management console and REST API.
 
 Customized provisioning can be useful where two starting entities depend on each other. For example, it is often necessary to delay start of one entity until another entity reaches a certain state, and to supply run-time information about the latter to the former.
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/location.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/location.md b/docs/guide/concepts/location.md
index 2a06cac..417d0a7 100644
--- a/docs/guide/concepts/location.md
+++ b/docs/guide/concepts/location.md
@@ -1,6 +1,6 @@
 ---
 title: Location
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/concepts/policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/policies.md b/docs/guide/concepts/policies.md
index ad8c0bb..495e57f 100644
--- a/docs/guide/concepts/policies.md
+++ b/docs/guide/concepts/policies.md
@@ -1,6 +1,6 @@
 ---
 title: Policies
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/code/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.md b/docs/guide/dev/code/index.md
index 1d4407b..6436023 100644
--- a/docs/guide/dev/code/index.md
+++ b/docs/guide/dev/code/index.md
@@ -25,11 +25,14 @@ cd usage/dist/target/brooklyn-dist/
 bin/brooklyn launch
 {% endhighlight %}
 
+{% comment %}
+TODO examples
 Plenty of examples are in the **examples** sub-dir,
 described [here]({{site.path.guide}}/use/examples).
+{% endcomment %}
 
 Information on using Brooklyn -- configuring locations (in `brooklyn.properties`) 
-and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}/use/guide/quickstart/index.html).
+and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}).
 This document is intended to help people become familiar with the codebase.
 
 ## Project Structure
@@ -74,8 +77,8 @@ Brooklyn is split into the following projects and sub-projects:
     * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts)
     * **qa**: longevity and stress tests
     * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test``
-* **``docs``**: the markdown source code for this documentation, as described [here]({{site.path.guide}}/dev/tips/update-docs.html)
-* **``examples``**: some canonical examples, as listed [here]({{site.path.guide}}/use/examples)
+* **``docs``**: the markdown source code for this documentation
+* **``examples``**: some canonical examples
 * **``sandbox``**: various projects, entities, and policies which the Brooklyn Project is incubating
 
  

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/code/tests.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/tests.md b/docs/guide/dev/code/tests.md
index f202dc2..6d2bbab 100644
--- a/docs/guide/dev/code/tests.md
+++ b/docs/guide/dev/code/tests.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Tests
 toc: /guide/toc.json
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/env/ide/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/ide/index.md b/docs/guide/dev/env/ide/index.md
index 3abae3c..0dddfc1 100644
--- a/docs/guide/dev/env/ide/index.md
+++ b/docs/guide/dev/env/ide/index.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: IDE Setup
 toc: /guide/toc.json
 ---
@@ -75,9 +75,8 @@ find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mk
   but for others (older ones) you may need to handcraft these 
   (either right-click the project in the Package Explorer and choose Configure,
   or edit the ``.project`` manually adding it to the project properties).
-  The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful. 
 
-If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.guide}}/meta/contact.html) and we can hopefully share our pearls.
+If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.website}}/community/) and we can hopefully share our pearls.
 (And if you have a tip we haven't mentioned please let us know that too!)
 
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/env/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/index.md b/docs/guide/dev/env/index.md
index ef00e89..8e1e422 100644
--- a/docs/guide/dev/env/index.md
+++ b/docs/guide/dev/env/index.md
@@ -10,4 +10,4 @@ children:
 - ide/
 ---
 
-TODO
\ No newline at end of file
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/env/maven-build.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/maven-build.md b/docs/guide/dev/env/maven-build.md
index 90aa6fa..e9b0f2e 100644
--- a/docs/guide/dev/env/maven-build.md
+++ b/docs/guide/dev/env/maven-build.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Maven Build
 toc: /guide/toc.json
 ---
@@ -24,12 +24,12 @@ Key things to note if you're new to Maven:
 * Add ``-DskipTests`` to skip tests. 
 
 * Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
-  ([tests described here](tests.html))
+  ([tests described here](../code/tests.html))
 
 * Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms.
 
 * You can also open and use the code in your favourite IDE,
-  although you may hit a few **[snags](ide.html)**
+  although you may hit a few **[snags](ide/)**
   (that link has some tips for resolving them too)
 
 
@@ -72,10 +72,6 @@ If there is a good reason that a file, pattern, or directory should be permanent
   
   ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}`` 
 
-* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line.
-  
-  ``wget {{site.url_root}}{{site.path.guide}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml`` 
-
 ## Appendix: Sample Output
 
 A healthy build will look something like the following,

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md
index 31dd7e1..a4f6ef9 100644
--- a/docs/guide/dev/index.md
+++ b/docs/guide/dev/index.md
@@ -8,12 +8,16 @@ breadcrumbs:
 children:
 - env/
 - code/
+- { link: "http://github.com/apache/incubator-brooklyn", title: "GitHub" }
 - code/tests.md
 - tips/
 - tips/logging.md
 - tips/debugging-remote-brooklyn.md
 ---
 
+{% comment %}
+TODO
+
 The Developer Guide contains information on working with the Brooklyn codebase.
 
 Of particular note to people getting started, there is:
@@ -28,3 +32,6 @@ And for the Brooklyn codebase itself, see:
 * Areas of Special Hairiness
 
 (All links are TODO.)
+{% endcomment %}
+
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/tips/debugging-remote-brooklyn.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/debugging-remote-brooklyn.md b/docs/guide/dev/tips/debugging-remote-brooklyn.md
index 23857e3..4d14e5f 100644
--- a/docs/guide/dev/tips/debugging-remote-brooklyn.md
+++ b/docs/guide/dev/tips/debugging-remote-brooklyn.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Brooklyn Remote Debugging
 toc: /guide/toc.json
 ---
@@ -19,27 +19,25 @@ Thankfully, the tools are available to do this, and setting it up is quite strai
 The first step is to ensure that your local copy of the source code is at the version used to build the remote Brooklyn
 instance. The git commit that was used to build Brooklyn is available via the REST API:
 
-```
-http://<remote-address>:<remote-port>/v1/server/version
-```
+    http://<remote-address>:<remote-port>/v1/server/version
 
 This should return details of the build as a JSON string similar to the following (formatted for clarity):
 
-```JSON
+{% highlight json %}
 {
     "version": "0.7.0-SNAPSHOT",
     "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224",
     "buildBranch": "UNKNOWN"
 }
-```
+{% endhighlight %}
 
 The value that we're interested in is `buildSha1`. This is the git commit that was used to build Brooklyn. We can now
 checkout and build the Brooklyn code at this commit by running the following in the root of your Brooklyn repo:
 
-```
-git checkout c0fdc15291702281acdebf1b11d431a6385f5224
-mvn clean install -DskipTests
-```
+{% highlight bash %}
+% git checkout c0fdc15291702281acdebf1b11d431a6385f5224
+% mvn clean install -DskipTests
+{% endhighlight %}
 
 Whilst building the code isn't strictly necessary, it can help prevent some IDE issues.
 
@@ -48,25 +46,24 @@ By default, Brooklyn does not listen for a debugger to be attached, however this
 which will require a restart of the Brooklyn node. To do this, SSH to the remote Brooklyn node and run the following in the
 root of the Brooklyn installation:
 
-```
+{% highlight bash %}
 # NOTE: Running this kill command will lose existing apps and machines if persistence is disabled.
-kill `cat pid_java`
-export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
-bin/brooklyn launch &
-```
+% kill `cat pid_java`
+% export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
+% bin/brooklyn launch &
+{% endhighlight %}
 
 If `JAVA_OPTS` is not set, Brooklyn will automatically set it to `"-Xms256m -Xmx1g -XX:MaxPermSize=256m"`, which is why
 we have prepended the agentlib settings with these values here.
 
 You should see the following in the console output:
 
-```
-Listening for transport dt_socket at address: 8888
-```
+    Listening for transport dt_socket at address: 8888
 
 This will indicate the Brooklyn is listening on port 8888 for a debugger to be attached.
 
 ## <a name="sshTunnel"></a>Creating an SSH tunnel
+
 If port 8888 is accessible on the remote Brooklyn server, then you can skip this step and simply use the address of the
 server in place of 127.0.0.1 in the [Connecting your IDE](#connectingIDE) section below. It will normally be possible to
 make the port accessible by configuring Security Groups, iptables, endpoints etc., but for a quick ad-hoc connection it's
@@ -74,7 +71,7 @@ usually simpler to create an SSH tunnel. This will create an open SSH connection
 on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local
 machine:
 
-```
+{% highlight bash %}
 # replace this with the address or IP of the remote Brooklyn node
 REMOTE_HOST=<remote-address>
 # if you wish to use a different port, this value must match the port specified in the JAVA_OPTS
@@ -86,15 +83,12 @@ SSH_USER=root
 # The private key file used to SSH to the remote node. If you use a password, see the alternative command below
 PRIVATE_KEY_FILE=~/.ssh/id_rsa 
 
-ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
-
-```
+% ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
+{% endhighlight %}
 
 If you use a password to SSH to the remote Brooklyn node, simply remove the `-i $PRIVATE_KEY_FILE` section like so:
 
-```
-ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
-```
+    ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
 
 If you are using a password to connect, you will be prompted to enter your password to connect to the remote node upon
 running the SSH command.
@@ -104,10 +98,12 @@ tunnel to port 8888 on the remote 127.0.0.1 interface. It should now be possible
 debugging.
 
 ## <a name="connectingIDE"></a> Connecting your IDE
+
 Setting up your IDE will differ depending upon which IDE you are using. Instructions are given here for Eclipse and
 IntelliJ, and have been tested with Eclipse Luna and IntelliJ Ultimate 14.
 
 ### Eclipse Setup
+
 To debug using Eclipse, first open the Brooklyn project in Eclipse (see [IDE Setup](../env/ide/)).
 
 Now create a debug configuration by clicking `Run` | `Debug Configurations...`. You will then be presented with the 
@@ -119,6 +115,7 @@ Connection Type should be set to 'Standard (Socket Attach)'. The Host should be
 and the Port should be set to 8888. Click 'Debug' to start debugging.
 
 ### IntelliJ Setup
+
 To debug using IntelliJ, first open the Brooklyn project in IntelliJ (see [IDE Setup](../env/ide/)).
 
 Now create a debug configuration by clicking `Run` | `Edit Configurations`. You will then be presented with the
@@ -134,6 +131,7 @@ configuration, then select the configuration from the configurations drop-down a
 debugging.
 
 ### Testing
+
 The easiest way to test that remote debugging has been setup correctly is to set a breakpoint and see if it is hit. An
 easy place to start is to create a breakpoint in the `ServerResource.java` class, in the `getStatus()` 
 method. 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md
index 9045fe9..ac173c0 100644
--- a/docs/guide/dev/tips/index.md
+++ b/docs/guide/dev/tips/index.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Miscellaneous Tips and Tricks
 ---
 
@@ -12,7 +12,7 @@ title: Miscellaneous Tips and Tricks
   
 * When debugging an entity, make sure the  [brooklyn.SSH logger](logging.html) is set to DEBUG and accessible.
  
-* Use tests heavily!  These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.path.guide}}/dev/build/ide.html)),
+* Use tests heavily!  These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.path.guide}}/dev/env/ide/)),
   and far quicker to spot problems than runtime, plus we get early-warning of problems introduced in the future.
   (In particular, Groovy's laxity with compilation means it is easy to introduce silly errors which good test coverage will find much faster.)
   
@@ -36,7 +36,7 @@ title: Miscellaneous Tips and Tricks
   Clusters will take such a ``MachineProvisioningLocation`` (or a singleton list); fabircs take a list of locations.
   Some PaaS systems have their own location model, such as ``OpenShiftLocation``.
 
-Finally, don't be shy about [talking with others]({{site.path.guide}}/meta/contact.html), 
+Finally, don't be shy about [talking with others]({{site.path.website}}/community/), 
 that's far better than spinning your wheels (or worse, having a bad experience),
 plus it means we can hopefully improve things for other people!
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/archetype.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/archetype.md b/docs/guide/java/archetype.md
index 482e51c..0bbf6f4 100644
--- a/docs/guide/java/archetype.md
+++ b/docs/guide/java/archetype.md
@@ -1,6 +1,6 @@
 ---
 title: Creating from a Maven Archetype
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/common-usage.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/common-usage.md b/docs/guide/java/common-usage.md
index e3cf54f..8f0ed32 100644
--- a/docs/guide/java/common-usage.md
+++ b/docs/guide/java/common-usage.md
@@ -1,8 +1,10 @@
 ---
 title: Common Classes and Entities
-layout: guide-normal
+layout: website-normal
 ---
 
+<!-- TODO old, needs work (refactoring!) and use of java_link -->
+
 ### Entity Class Hierarchy
 
 By convention in Brooklyn the following words have a particular meaning, both as types (which extend ``Group``, which extends ``Entity``) and when used as words in other entities (such as ``TomcatFabric``):
@@ -39,4 +41,100 @@ These include:
 - **PaaS**: Cloud Foundry, Stackato; OpenShift
 
 
-®
\ No newline at end of file
+### Sensors
+
+Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example:
+{% highlight java %}
+/** a sensor for saying hi (illustrative), carrying a String value 
+    which is typically the name of the person to whom we are saying hi */
+public static final Sensor<String> HELLO_SENSOR = ...
+
+{% endhighlight %}
+
+If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs.
+
+Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``.
+
+Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` – an attribute value being reported on change or periodically – or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT".
+
+<!---
+TODO check classes above; is this much detail needed here?
+-->
+
+Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON:
+        
+    {
+      config : {
+        url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
+        status : "running"
+      }
+      workrate : {
+        msgsPerSec : 432
+      }
+    }
+
+Sensor values are defined as statics, which can be used to programmatically drive the subscription.
+
+A range of `Feed` instances are available to simplify reading sensor information.
+
+
+### Effectors
+
+Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows:
+
+{% highlight java %}
+/** an effector which returns no value,
+    but which causes the entity to emit a HELLO sensor event */
+public static Effector<Void> SAY_HI = ...
+
+{% endhighlight %}
+
+Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map.
+
+Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning.
+
+The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location).
+
+It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
+
+
+### Tasks and the Execution Manager
+
+The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**.
+Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface.
+
+By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling
+``ExecutionManager.getTasksWithTag(...)``.
+
+The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended.
+    
+    ExecutionManager em = []
+    em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
+    em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
+    assert em.getTasksWithTag("a").size()==2
+    assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
+    Thread.sleep(1500)
+    assert em.getTasksWithTag("a").size()==2
+    assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
+
+It is possible to define `ParallelTask` and sequential `Task` instancess 
+and to specify inter-task relationships with `TaskPreprocessor` instances. 
+This allows building quite sophisticated workflows relatively easily.
+
+Continuing the example above, submitting a `SequentialTask` 
+or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)`` 
+will cause ``Two Mississippi`` to run after ``One Mississippi`` completes.
+
+It is also possible to register `ScheduledTask` instances which run periodically.
+
+**The `Tasks` factory supplies a number of conveniences including builders to make working with tasks easier
+and should be the entry point in most cases.**
+
+
+
+### Subscriptions and the Subscription Manager
+
+In addition to scheduled tasks, tasks can triggered by subscriptions on other events including sensors.
+
+To register low-level listeners to events, use the `SubscriptionManager` API.
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/defining-and-deploying.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/defining-and-deploying.md b/docs/guide/java/defining-and-deploying.md
index 084b4f6..8f56000 100644
--- a/docs/guide/java/defining-and-deploying.md
+++ b/docs/guide/java/defining-and-deploying.md
@@ -1,6 +1,6 @@
 ---
 title: Defining and Deploying
-layout: guide-normal
+layout: website-normal
 ---
 
 ## Intro
@@ -33,8 +33,8 @@ provides a template to follow.
 
 ## Deploying the Application
 
-If you have not already done so, follow the section in the 
-[Getting Started Guide]({{site.path.guide}}/use/guide/quickstart/index.html) to create a `brooklyn.properties` 
+If you have not already done so, follow the instructions 
+[here]({{site.path.guide}}/ops/locations/) to create a `brooklyn.properties` 
 file containing credentials for your preferred cloud provider. 
 
 To launch this application, build the project and run the `start.sh` script in the resulting assembly:
@@ -69,17 +69,19 @@ and exposes operations ("effectors") that can be performed on entities.
 ## What Next?
  
 In addition to the sample project created by the archetype, with its README and
-`assembly` build, you can find additional code related to this example included with Brooklyn as the ``simple-web-cluster`` example,
+`assembly` build, you can find additional code related to this example included with Brooklyn as the ``simple-web-cluster`` example.
+{% comment %}
 described [in detail here]({{site.path.guide}}/use/examples/webcluster).
+{% endcomment %}
 
 For your applications, you might want to mix in other data stores, messaging systems, or on-line services including PaaS.
 Brooklyn supports some of these out-of-the-box, including a wide-range of tools which it can use Whirr to provision, such as Hadoop.
 But if you have something you don't see, 
-[let us know]({{site.path.guide}}/meta/contact.html) -- 
+[let us know]({{site.path.website}}/community/) -- 
 we want to work with you to 
-[write a new entity]({{site.path.guide}}/dev/code/entity.html) or
-[policy]({{site.path.guide}}/dev/code/policy.html) 
-and [contribute it]({{site.path.guide}}/dev/how-to-contrib.html).
+[write a new entity]({{site.path.guide}}/java/entity.html) or
+[policy]({{site.path.guide}}/java/policy.html) 
+and [contribute it]({{site.path.website}}/developers/how-to-contribute.html).
 
 
 <!--

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/entities.md b/docs/guide/java/entities.md
index f529762..aae674d 100644
--- a/docs/guide/java/entities.md
+++ b/docs/guide/java/entities.md
@@ -1,6 +1,6 @@
 ---
 title: Custom Entity Development
-layout: guide-normal
+layout: website-normal
 ---
 
 This section details how to create new custom application components or groups as brooklyn entities.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/entity.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/entity.md b/docs/guide/java/entity.md
index 6d780be..6828a17 100644
--- a/docs/guide/java/entity.md
+++ b/docs/guide/java/entity.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Writing an Entity
 ---
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/policies.md b/docs/guide/java/policies.md
index 5bc8289..9457f72 100644
--- a/docs/guide/java/policies.md
+++ b/docs/guide/java/policies.md
@@ -1,6 +1,6 @@
 ---
 title: Policies
-layout: guide-normal
+layout: website-normal
 
 ---
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/policy.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/policy.md b/docs/guide/java/policy.md
index d785f0d..fbb79db 100644
--- a/docs/guide/java/policy.md
+++ b/docs/guide/java/policy.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Writing a Policy
 ---
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/service-state.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/service-state.md b/docs/guide/java/service-state.md
index 32212bc..2abbf65 100644
--- a/docs/guide/java/service-state.md
+++ b/docs/guide/java/service-state.md
@@ -1,6 +1,6 @@
 ---
 title: Service State
-layout: guide-normal
+layout: website-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/java/topology-dependencies-management-policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/topology-dependencies-management-policies.md b/docs/guide/java/topology-dependencies-management-policies.md
index 8039d2c..249c99a 100644
--- a/docs/guide/java/topology-dependencies-management-policies.md
+++ b/docs/guide/java/topology-dependencies-management-policies.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Topology, Dependencies, and Management Policies
 title_in_menu: Topology, Dependencies, and Management Policies
 --- 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/misc/download.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/download.md b/docs/guide/misc/download.md
index 011d9f3..c79ef16 100644
--- a/docs/guide/misc/download.md
+++ b/docs/guide/misc/download.md
@@ -1,18 +1,22 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Downloads
 ---
 {% include fields.md %}
 
-First time user? The [getting started]({{ site.path.guide }}/use/guide/quickstart/index.html) guide will walk you through downloading Brooklyn, setup of your `brooklyn.properties` and `catalog.xml` files, and then trying the [examples](#examples). 
+**Brooklyn in Apache has not yet made an official clean binary release. 
+The downloads on this page have not been voted on and should be used at your own risk.
+Additionally some links on this page may not work until those builds have been officially released.
+For more information, see the [main download page]({{ site.path.website }}/download/).**
+
 
 ## Download Version {{ site.brooklyn-version }}
 
-<table>
+<table class="table">
   <tr>
 	<th style='text-align:left'>Download</th>
 	<th style='text-align:left'>File/Format</th>
-	<th>checksums <small><a href="/meta/verify.html" title='Instructions on verifying the integrity of your downloads.'>(?)</a></small></th>
+	<th>checksums <small><a href="{{ site.path.website }}/download/verify.html" title='Instructions on verifying the integrity of your downloads.'>(?)</a></small></th>
   </tr>
   <tr>
 	<td style='text-align:left;vertical-align:top' rowspan='2'>Distro</td>
@@ -84,9 +88,10 @@ and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-all/) for snapshot versio
 
 ## Release Notes
 
-Release notes can be found [here]({{ site.path.guide }}/start/release-notes.html).
-
+Release notes can be found [here]({{ site.path.guide }}/misc/release-notes.html).
 
+{% comment %}
+TODO
 <a name="examples"></a>
 
 ## Examples
@@ -95,6 +100,7 @@ Examples can be found in the main Brooklyn codebase, in the `/examples` director
 
 A good example to start with is the [Elastic Web Cluster]({{site.path.guide}}/use/examples/webcluster.html).
 
+{% endcomment %}
 
 <a name="maven"></a>
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/misc/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/index.md b/docs/guide/misc/index.md
index 8bb1e0f..a0c6cb1 100644
--- a/docs/guide/misc/index.md
+++ b/docs/guide/misc/index.md
@@ -17,4 +17,4 @@ Further documentation specific to this version of Brooklyn includes:
 * [{{ item.title_in_menu }}]({{ item.url }})
 {% endfor %}
 
-Also see the [other versions]({{ path.guide }}/meta/versions.html) or [general documentation]({{ path.guide }}/documentation/).
+Also see the [other versions]({{ site.path.website }}/meta/versions.html) or [general documentation]({{ site.path.website }}/documentation/).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/misc/javadoc/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/javadoc/index.md b/docs/guide/misc/javadoc/index.md
index c44b6e3..5cf9ebc 100644
--- a/docs/guide/misc/javadoc/index.md
+++ b/docs/guide/misc/javadoc/index.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: API Reference
 toc: ../../toc.json
 ---

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/misc/known-issues.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/known-issues.md b/docs/guide/misc/known-issues.md
index 5514b13..db54a06 100644
--- a/docs/guide/misc/known-issues.md
+++ b/docs/guide/misc/known-issues.md
@@ -1,5 +1,5 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Known Issues
 ---
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/misc/release-notes.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/release-notes.md b/docs/guide/misc/release-notes.md
index 0bdd3d0..8683eb8 100644
--- a/docs/guide/misc/release-notes.md
+++ b/docs/guide/misc/release-notes.md
@@ -1,12 +1,10 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Release Notes
 ---
 
 ## Version {{ site.brooklyn-version }}
 
-TODO: breacrumbs {{ page.breadcrumb_paths }}.
-
 {% if SNAPSHOT %}
 **You are viewing a SNAPSHOT release (master branch), so this list is incomplete.**
 {% endif %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/brooklyn_properties.md b/docs/guide/ops/brooklyn_properties.md
new file mode 100644
index 0000000..da8b848
--- /dev/null
+++ b/docs/guide/ops/brooklyn_properties.md
@@ -0,0 +1,175 @@
+---
+title: brooklyn.properties
+layout: website-normal
+children:
+- { section: Quick Setup }
+- { section: Locations }
+- { section: Java }
+- { section: Authentication }
+- { section: Entitlements }
+- { section: HTTPS Configuration }
+---
+
+{% include fields.md %}
+
+The file `~/.brooklyn/brooklyn.properties` is read when Brooklyn starts
+to load server configuration values.
+A different properties file can be specified either additionally or instead
+through [CLI options](cli.html#configuration). 
+
+A template [brooklyn.properties]({{brooklyn_properties_url_path}}) file is available,
+with abundant comments.
+
+
+## Quick Setup
+
+The most common properties set in this file are for access control.
+Without this, Brooklyn will bind only to localhost or will create a random
+password written to the log for use on other networks.
+The simplest way to specify users and passwords is:
+ 
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin,bob
+brooklyn.webconsole.security.user.admin.password=AdminPassw0rd
+brooklyn.webconsole.security.user.bob.password=BobPassw0rd
+{% endhighlight %}
+
+The properties file *must* have permissions 600 
+(i.e. readable and writable only by the file's owner),
+for some security.
+
+In many cases, it is preferable instead to use an external credentials store such as LDAP
+or at least to have passwords in this file.
+Information on configuring these is [below](#authentication). 
+
+If coming over a network it is highly recommended additionally to use `https`.
+This can be configured with:
+
+{% highlight properties %}
+brooklyn.webconsole.security.https.required=true
+{% endhighlight %}
+
+More information, including setting up a certificate, is described [further below](#https-configuration).
+
+
+## Locations
+
+Information on defining locations in the `brooklyn.properties` file is available [here](locations/).
+
+
+## Java
+
+Arbitrary data can be set in the `brooklyn.properties`.
+This can be accessed in java using `ManagementContext.getConfig(KEY)`.
+
+
+## Authentication
+
+**Security Providers** are the mechanism by which different authentication authorities are plugged in to Brooklyn.
+These can be configured by specifying `brooklyn.webconsole.security.provider` equal 
+to the name of a class implementing `SecurityProvider`.
+An implementation of this could point to Spring, LDAP, OpenID or another identity management system.
+
+The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords
+which should be specified as configuration parameters e.g. in `brooklyn.properties`.
+This configuration could look like:
+
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.salt=OHDf
+brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
+{% endhighlight %}
+
+The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users.
+
+To generate this, the brooklyn CLI can be used:
+{% highlight bash %}
+brooklyn generate-password --user admin
+
+Enter password: 
+Re-enter password: 
+
+Please add the following to your brooklyn.properies:
+
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.salt=OHDf
+brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
+{% endhighlight %}
+
+Alternatively, in dev/test environments where a lower level of security is required,
+the syntax `brooklyn.webconsole.security.user.<username>=<password>` can be used for
+each `<username>` specified in the `brooklyn.webconsole.security.users` list.
+
+Other security providers available include:
+
+* **No one**: `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider`
+  will block all logins (e.g. if not using the web console)
+* **No security**: `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider`
+  will allow logins with no credentials (e.g. in secure dev/test environments) 
+* **LDAP**: `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.LdapSecurityProvider`
+  will cause Brooklyn to call to an LDAP server to authenticate users;
+  `brooklyn.webconsole.security.ldap.{url,realm}` must also be set as `brooklyn.properties`
+
+
+## Entitlements
+
+In addition to login access, fine-grained permissions including 
+seeing entities, creating applications, seeing sensors, and invoking effectors
+can be defined on a per-user *and* per-target (e.g. which entity/effector) basis
+using an **Entitlement Manager**.
+
+This can be set globally with the property:
+
+{% highlight properties %}
+brooklyn.entitlements.global=<class>
+{% endhighlight %}
+
+The default entitlement manager is one which responds to per-user entitlement rules,
+and understands:
+
+* `root`:  full access, including to the Groovy console
+* `readonly`:  read-only access to almost all information
+* `minimal`:  access only to server stats, for use by monitoring systems
+
+{% comment %}
+TODO in Entitlements
+
+These keywords are also understood at the `global` level, so to grant full access to `admin`
+but read-only access to any other authenticated users, you can write:
+
+{% highlight properties %}
+brooklyn.entitlements.global=readonly
+brooklyn.entitlements.user.admin=root
+{% endhighlight %}
+
+{% endcomment %}
+
+For more information, see {% include java_link.html class_name="EntitlementManager" package_path="brooklyn/management/entitlement" project_subpath="api" %}.
+
+
+## HTTPS Configuration
+
+To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the
+following command:
+
+{% highlight bash %}
+% keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key -storepass mypassword -validity 360 -keysize 2048
+{% endhighlight %}
+
+You will then be prompted to enter you name and organization details. This will create a keystore with the password `mypassword`
+- you should use your own secure password, which will be the same password used in your brooklyn.properties (below). 
+You will also need to replace `<path-to-keystore-directory>` with the full path of the folder where you wish to store your
+keystore. 
+
+The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server 
+name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed 
+certificate from a trusted certifying authority should be used instead
+
+To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
+
+{% highlight properties %}
+brooklyn.webconsole.security.https.required=true
+brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key
+brooklyn.webconsole.security.keystore.password=mypassword
+brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
+{% endhighlight %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/ops/catalog/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/catalog/index.md b/docs/guide/ops/catalog/index.md
new file mode 100644
index 0000000..123cc40
--- /dev/null
+++ b/docs/guide/ops/catalog/index.md
@@ -0,0 +1,174 @@
+---
+title: Catalog
+layout: website-normal
+children:
+- { section: Catalog Items }
+- { section: Adding to the Catalog, title: Adding and Deleting } 
+- { section: Versioning } 
+- { section: special-reqs, title: Wizard } 
+---
+
+Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints. 
+These can be deployed directly or referenced by other blueprints. 
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from 
+the web-console's "Catalog" tab of the "Create Application" wizard dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog Items
+
+An item to be added to the catalog is defined in YAML. This follows the syntax of a 
+YAML blueprint with an addition `brooklyn.catalog` section giving 
+the metadata needed to register the blueprint in the catalog:
+
+{% highlight yaml %}
+brooklyn.catalog:
+  id: my-MySQL
+  version: 1.0
+  iconUrl: classpath://mysql.png
+  description: MySql is an open source relational database management system (RDBMS)
+  libraries:
+    - url: http://example.com/path/to/my-dependency-1.2.3.jar
+    - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` fields:
+
+- The `id: MySQL` line specifies a unique ID used by Brooklyn to identify the catalog item. 
+  Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` line provides a unique version for the *blueprint*. 
+  Note that this is typically *not* the version of the software being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional line where an icon can be specified 
+  for use with the item (in the "Add Application" dialog and elsewhere).
+  Note that `classpath` URLs *cannot* refer to items in the OSGi bundle 
+  (to prevent requiring all OSGi bundles to be loaded at launch);
+  use the server supplying the OSGi bundles or the `conf` folder of the Brooklyn distro instead.
+- The `description: ...` line, also optional, allows supplying a free-format description of the blueprint.
+
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath.
+These URL's should be to stable OSGi bundles;
+if the contents at any of these URLs changes, the behaviour of the blueprint may change 
+whenever a bundle is reloaded in a Brooklyn server,
+and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
+To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.
+
+To reference a catalog item in another blueprint, simply reference its ID and optionally its version number.
+For example: 
+
+{% highlight yaml %}
+services:
+- type: my-MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, `POST` the YAML file to `/v1/catalog` endpoint in
+Brooklyn's REST API.
+To do this using `curl`:
+
+{% highlight bash %}
+curl http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
+{% endhighlight %}
+
+
+
+### Deleting from the Catalog
+
+You can delete a versioned item from the catalog using the same endpoint at the REST API. 
+For example, to delete the item with id `my-MySQL` and version `1.0` with `curl`:
+
+{% highlight bash %}
+curl -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
+{% endhighlight %}
+
+**Note:** Catalog items should not be deleted if there are running apps which were created using the same item. 
+During rebinding the catalog item is used to reconstruct the entity.
+
+
+### Versioning
+
+Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part.
+For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
+
+The combination of `id:version` strings must be unique across the catalog.
+It is an error to deploy the same version of an existing item:
+to update a blueprint, it is recommended to increase its version number;
+alternatively in some cases it is permitted to delete an `id:version` instance
+and then re-deploy.
+If no version is specified, re-deploying will automatically
+increment an internal version number for the catalog item.
+
+When referencing a blueprint, if a version number is not specified 
+the latest non-snapshot version will be loaded when an entity is instantiated.
+
+
+<a id="special-reqs"/>
+
+### Special Requirements for the "Create Application" Wizard Dialog
+
+For a blueprint in the catalog to be accessible via the 'Create Application' dialog, it must be an Application 
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+In contrast, if a YAML blueprint is deployed direct via the REST API, then this is not necessary.
+
+For example, the MySql catalog item defined previously could be re-written to use a
+`brooklyn.entity.basic.BasicApplication`, because no application-specific logic is 
+required other than to pass-through the start and stop commands.
+the `MySqlNode` is added as a child of the `BasicApplication`.
+
+{% highlight yaml %}
+brooklyn.catalog:
+  id: my-MySQL
+  version: 1.0
+  iconUrl: classpath://mysql.png
+  description: MySql is an open source relational database management system (RDBMS)
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.basic.BasicApplication
+  brooklyn.children:
+  - type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+When added to the catalog via the HTTP `POST` command, the blueprint will appear in the 'Create Application' dialog
+as shown here:
+
+[![MySQL in Brooklyn Catalog](mysql-in-catalog-w700.png "MySQL in Brooklyn Catalog")](mysql-in-catalog.png) 
+
+When deploying a new version of a blueprint, the catalog will show both the previous and the new versions 
+of the blueprint. You may wish to delete the older version, assuming no applications currently running
+are using that old version.
+
+<!--
+TODO: Should improve the 'Create Application' dialog, so that the two versions don't appear on the front page.
+Currently they are indistinguisable, if they have the same description/icon.
+-->
+
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+<!--
+TODO: Add documentation to explain that the brooklyn.catalog section can contain a libraries array, each item pointing to 
+an OSGi bundle where the code for the blueprint is hosted. Every type from the blueprint will be searched for in the 
+libraries first and then on the standard Brooklyn classpath.*
+-->
+
+<!--
+TODO: Add documentation about adding policies to the catalog, and explaining how to add items to 
+the UI using the plus icon on the catalog tab*
+
+TODO: describe entity addition (this just covers app addition)
+
+TODO: describe how to use the web-console GUI
+-->

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/ops/catalog/mysql-in-catalog-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/catalog/mysql-in-catalog-w700.png b/docs/guide/ops/catalog/mysql-in-catalog-w700.png
new file mode 100644
index 0000000..f370249
Binary files /dev/null and b/docs/guide/ops/catalog/mysql-in-catalog-w700.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/8560033d/docs/guide/ops/catalog/mysql-in-catalog.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/catalog/mysql-in-catalog.png b/docs/guide/ops/catalog/mysql-in-catalog.png
new file mode 100644
index 0000000..685455d
Binary files /dev/null and b/docs/guide/ops/catalog/mysql-in-catalog.png differ


Mime
View raw message