diff --git a/docs/scripts/defaults.md.j2 b/docs/scripts/defaults.md.j2
index 04738cb..35e8d29 100644
--- a/docs/scripts/defaults.md.j2
+++ b/docs/scripts/defaults.md.j2
@@ -1,22 +1,21 @@
 # Build System Config Glossary
 
-{{ def_docs['frontmatter']['description'] }}
-
+{{ frontmatter }}
 {% for key, val in def_docs|dictsort %}
-### {{ key }}
-
+## {{ key }}
+{% if val['description'] != ''%}
 {{ val['description'] }}
-
+{% endif %}
 Default value:
-```
+
+```yaml
 {{ val['defval_pp'] }}
 ```
 
 Used in:
 
 {% for file in val['reflist']|sort(attribute='path') -%}
- - [{{ file.path }}]({{ file.link }})
+- [{{ file.path }}]({{ file.link }})
 {% endfor -%}
-
 {% endfor %}
 
diff --git a/docs/scripts/defaultsdoc.py b/docs/scripts/defaultsdoc.py
index f75fa85..c17ee49 100644
--- a/docs/scripts/defaultsdoc.py
+++ b/docs/scripts/defaultsdoc.py
@@ -20,7 +20,6 @@
 import jinja2
 import logging
 import os
-import pprint
 import re
 import sys
 import xml.etree.ElementTree as ET
@@ -56,7 +55,7 @@
 args = parser.parse_args()
 
 # find the branch we're on via the repo manifest
-manifest_path =  os.path.abspath("../../.repo/manifest.xml")
+manifest_path = os.path.abspath("../../.repo/manifest.xml")
 try:
     tree = ET.parse(manifest_path)
     manifest_xml = tree.getroot()
@@ -69,15 +68,12 @@
 role_defs = []
 profile_defs = []
 group_defs = []
-
-# frontmatter section is any text at the top of the descriptions.md file, and
-# comes before all other sections
-def_docs = {'frontmatter':{'description':''}}
+def_docs = {}
 
 # find all the files to be processed
 for dirpath, dirnames, filenames in os.walk(args.playbook_dir):
     basepath = re.sub(args.playbook_dir, '', dirpath)
-    for filename in filenames :
+    for filename in filenames:
         filepath = os.path.join(basepath, filename)
 
         if fnmatch.fnmatch(filepath, "roles/*/defaults/*.yml"):
@@ -90,7 +86,6 @@
             group_defs.append(filepath)
 
 
-
 for rd in role_defs:
     rd_vars = {}
     # trim slash so basename grabs the final directory name
@@ -100,10 +95,10 @@
         rd_partialpath = os.path.join(rd_basedir, rd)
 
         # partial URL, without line nums
-        rd_url = "https://github.com/opencord/platform-install/tree/%s/%s" % (repo_branch, rd)
+        rd_url = "https://github.com/opencord/platform-install/tree/%s/%s" % (
+            repo_branch, rd)
 
-        
-        rd_fh= open(rd_fullpath, 'r')
+        rd_fh = open(rd_fullpath, 'r')
 
         # markedloader is for line #'s
         loader = markedyaml.MarkedLoader(rd_fh.read())
@@ -124,27 +119,39 @@
 
         for key, val in rd_vars.iteritems():
 
-           # build full URL to lines. Lines numbered from zero, so +1 on them to match github
-           if marked_vars[key].start_mark.line == marked_vars[key].end_mark.line:
-               full_url = "%s#L%d" % (rd_url, marked_vars[key].start_mark.line+1)
-           else:
-               full_url = "%s#L%d-L%d" % (rd_url, marked_vars[key].start_mark.line, marked_vars[key].end_mark.line)
+            # build full URL to lines. Lines numbered from zero, so +1 on them
+            # to match github
+            if marked_vars[key].start_mark.line == marked_vars[
+                    key].end_mark.line:
+                full_url = "%s#L%d" % (rd_url,
+                                       marked_vars[key].start_mark.line + 1)
+            else:
+                full_url = "%s#L%d-L%d" % (rd_url,
+                                           marked_vars[key].start_mark.line,
+                                           marked_vars[key].end_mark.line)
 
-           if key in def_docs:
+            if key in def_docs:
                 if def_docs[key]['defval'] == val:
-                    def_docs[key]['reflist'].append({'path':rd_partialpath, 'link':full_url})
+                    def_docs[key]['reflist'].append(
+                        {'path': rd_partialpath, 'link': full_url})
                 else:
-                    LOG.error(" %s has different default > %s : %s" % (rd, key, val))
-           else:
-                to_print = { str(key): val }
-                pp = yaml.dump(to_print, indent=4, allow_unicode=False, default_flow_style=False)
+                    LOG.error(
+                        " %s has different default > %s : %s" %
+                        (rd, key, val))
+            else:
+                to_print = {str(key): val}
+                pp = yaml.dump(
+                    to_print,
+                    indent=4,
+                    allow_unicode=False,
+                    default_flow_style=False)
 
                 def_docs[key] = {
-                        'defval': val,
-                        'defval_pp': pp,
-                        'description': "",
-                        'reflist': [{'path':rd_partialpath, 'link':full_url}],
-                        }
+                    'defval': val,
+                    'defval_pp': pp,
+                    'description': "",
+                    'reflist': [{'path': rd_partialpath, 'link': full_url}],
+                }
 
 # read in descriptions file
 descriptions = {}
@@ -158,7 +165,7 @@
 
         if desc_header:
             # add previous description to dict
-            descriptions[desc_name] = desc_lines
+            descriptions[desc_name] = desc_lines.strip()
 
             # set this as the next name, wipe out lines
             desc_name = desc_header.group(1)
@@ -166,14 +173,19 @@
         else:
             desc_lines += d_l
 
-    descriptions[desc_name] = desc_lines
+    descriptions[desc_name] = desc_lines.strip()
+
+# Get the frontmatter out of descriptions, and remove the header line
+frontmatter = re.sub(r'^#.*\n\n', '', descriptions.pop('frontmatter', None))
 
 # add descriptions to def_docs
 for d_name, d_text in descriptions.iteritems():
     if d_name in def_docs:
         def_docs[d_name]['description'] = d_text
     else:
-        LOG.error("Description exists for '%s' but doesn't exist in defaults" % d_name)
+        LOG.error(
+            "Description exists for '%s' but doesn't exist in defaults" %
+            d_name)
 
 # check for missing descriptions
 for key in sorted(def_docs):
@@ -182,10 +194,10 @@
 
 # Add to template and write to output file
 j2env = jinja2.Environment(
-    loader = jinja2.FileSystemLoader('.')
+    loader=jinja2.FileSystemLoader('.')
 )
 
 template = j2env.get_template(args.template)
 
 with open(args.output, 'w') as f:
-    f.write(template.render(def_docs=def_docs))
+    f.write(template.render(def_docs=def_docs, frontmatter=frontmatter))
diff --git a/docs/scripts/descriptions.md b/docs/scripts/descriptions.md
index f87b69a..91eae23 100644
--- a/docs/scripts/descriptions.md
+++ b/docs/scripts/descriptions.md
@@ -1,3 +1,4 @@
+# Build Variable Descriptions
 
 This page documents all the configuration variables that can be set in a [POD
 config](install.md#pod-config), [scenario](install.md#scenarios), or
@@ -5,9 +6,9 @@
 
 These variables are used in and apply to the following repositories:
 
- - [cord](https://github.com/opencord/cord) (aka "build" when checked out)
- - [maas](https://github.com/opencord/maas)
- - [platform-install](https://github.com/opencord/platform-install)
+- [cord](https://github.com/opencord/cord) (aka "build" when checked out)
+- [maas](https://github.com/opencord/maas)
+- [platform-install](https://github.com/opencord/platform-install)
 
 ## addresspool_public_cidr
 
@@ -370,8 +371,6 @@
 
 Hostname (or IP) for the ElasticStack logging host machine.
 
-
-
 ## management_hosts_net_cidr
 
 CIDR for the management_hosts VTN network.
@@ -536,11 +535,13 @@
 
 ## site_name
 
-Machine readable name to use for the CORD site. This should be one word, without spaces.
+Machine readable name to use for the CORD site. This should be one word,
+without spaces.
 
 ## site_suffix
 
-The DNS suffix applied to all machines created for this site. Must be a valid DNS name.
+The DNS suffix applied to all machines created for this site. Must be a valid
+DNS name.
 
 ## ssh_ca_phrase
 
@@ -763,6 +764,7 @@
 profile. Deprecated, see: [xos_new_tosca_config_templates](#xosnewtoscaconfigtemplates)
 
 ## xos_new_tosca_config_templates
+
 List of XOS tosca templates to load that make up the service graph of a
 profile.
 
diff --git a/docs/scripts/markedyaml.py b/docs/scripts/markedyaml.py
index f7c1484..95cd641 100644
--- a/docs/scripts/markedyaml.py
+++ b/docs/scripts/markedyaml.py
@@ -20,17 +20,17 @@
 # Request for licensing clarification made on 2017-09-19
 # Contains improvements to support more types (bool/int/etc.)
 
-import yaml
 from yaml.composer import Composer
-from yaml.reader import Reader
-from yaml.scanner import Scanner
-from yaml.composer import Composer
-from yaml.resolver import Resolver
+from yaml.constructor import SafeConstructor
 from yaml.parser import Parser
-from yaml.constructor import Constructor, BaseConstructor, SafeConstructor
+from yaml.reader import Reader
+from yaml.resolver import Resolver
+from yaml.scanner import Scanner
+
 
 def create_node_class(cls):
     class node_class(cls):
+
         def __init__(self, x, start_mark, end_mark):
             cls.__init__(self, x)
             self.start_mark = start_mark
@@ -41,18 +41,21 @@
     node_class.__name__ = '%s_node' % cls.__name__
     return node_class
 
+
 dict_node = create_node_class(dict)
 list_node = create_node_class(list)
 unicode_node = create_node_class(unicode)
 int_node = create_node_class(int)
 float_node = create_node_class(float)
 
+
 class NodeConstructor(SafeConstructor):
     # To support lazy loading, the original constructors first yield
     # an empty object, then fill them in when iterated. Due to
     # laziness we omit this behaviour (and will only do "deep
     # construction") by first exhausting iterators, then yielding
     # copies.
+
     def construct_yaml_map(self, node):
         obj, = SafeConstructor.construct_yaml_map(self, node)
         return dict_node(obj, node.start_mark, node.end_mark)
@@ -80,31 +83,33 @@
 
 
 NodeConstructor.add_constructor(
-        u'tag:yaml.org,2002:map',
-        NodeConstructor.construct_yaml_map)
+    u'tag:yaml.org,2002:map',
+    NodeConstructor.construct_yaml_map)
 
 NodeConstructor.add_constructor(
-        u'tag:yaml.org,2002:seq',
-        NodeConstructor.construct_yaml_seq)
+    u'tag:yaml.org,2002:seq',
+    NodeConstructor.construct_yaml_seq)
 
 NodeConstructor.add_constructor(
-        u'tag:yaml.org,2002:str',
-        NodeConstructor.construct_yaml_str)
+    u'tag:yaml.org,2002:str',
+    NodeConstructor.construct_yaml_str)
 
 NodeConstructor.add_constructor(
-        u'tag:yaml.org,2002:bool',
-        NodeConstructor.construct_yaml_bool)
+    u'tag:yaml.org,2002:bool',
+    NodeConstructor.construct_yaml_bool)
 
 NodeConstructor.add_constructor(
-        u'tag:yaml.org,2002:int',
-        NodeConstructor.construct_yaml_int)
+    u'tag:yaml.org,2002:int',
+    NodeConstructor.construct_yaml_int)
 
 NodeConstructor.add_constructor(
-        u'tag:yaml.org,2002:float',
-        NodeConstructor.construct_yaml_float)
+    u'tag:yaml.org,2002:float',
+    NodeConstructor.construct_yaml_float)
 
 
-class MarkedLoader(Reader, Scanner, Parser, Composer, NodeConstructor, Resolver):
+class MarkedLoader(Reader, Scanner, Parser, Composer,
+                   NodeConstructor, Resolver):
+
     def __init__(self, stream):
         Reader.__init__(self, stream)
         Scanner.__init__(self)
@@ -113,6 +118,6 @@
         NodeConstructor.__init__(self)
         Resolver.__init__(self)
 
+
 def get_data(stream):
     return MarkedLoader(stream).get_data()
-