diff --git a/Allura/allura/lib/app_globals.py b/Allura/allura/lib/app_globals.py
index 9917dd4..fffe3d0 100644
--- a/Allura/allura/lib/app_globals.py
+++ b/Allura/allura/lib/app_globals.py
@@ -254,6 +254,8 @@
             stats=_cache_eps('allura.stats'),
             site_stats=_cache_eps('allura.site_stats'),
             admin=_cache_eps('allura.admin'),
+            # macro eps are used solely for ensuring that external macros are
+            # imported (after load, the ep itself is not used)
             macros=_cache_eps('allura.macros'),
         )
 
diff --git a/Allura/allura/lib/macro.py b/Allura/allura/lib/macro.py
index 957fcb8..efb1433 100644
--- a/Allura/allura/lib/macro.py
+++ b/Allura/allura/lib/macro.py
@@ -164,7 +164,7 @@
 def get_projects_for_macro(
         category=None, display_mode='grid', sort='last_updated',
         show_total=False, limit=100, labels='', award='', private=False,
-        columns=1, show_proj_icon=True, show_download_button=True, show_awards_banner=True,
+        columns=1, show_proj_icon=True, show_download_button=False, show_awards_banner=True,
         grid_view_tools='',
         initial_q={}):
     from allura.lib.widgets.project_list import ProjectList
@@ -267,7 +267,7 @@
 @macro('neighborhood-wiki')
 def projects(category=None, display_mode='grid', sort='last_updated',
              show_total=False, limit=100, labels='', award='', private=False,
-             columns=1, show_proj_icon=True, show_download_button=True, show_awards_banner=True,
+             columns=1, show_proj_icon=True, show_download_button=False, show_awards_banner=True,
              grid_view_tools=''):
     initial_q = dict(neighborhood_id=c.project.neighborhood_id)
     return get_projects_for_macro(
@@ -281,7 +281,7 @@
 @macro('userproject-wiki')
 def my_projects(category=None, display_mode='grid', sort='last_updated',
                 show_total=False, limit=100, labels='', award='', private=False,
-                columns=1, show_proj_icon=True, show_download_button=True, show_awards_banner=True,
+                columns=1, show_proj_icon=True, show_download_button=False, show_awards_banner=True,
                 grid_view_tools=''):
 
     myproj_user = c.project.user_project_of
diff --git a/Allura/allura/templates/neighborhood_help.html b/Allura/allura/templates/neighborhood_help.html
index ed57b53..5c5d27a 100644
--- a/Allura/allura/templates/neighborhood_help.html
+++ b/Allura/allura/templates/neighborhood_help.html
@@ -45,7 +45,7 @@
     <li><code>display_mode</code> = grid/list.  Default is 'grid'</li>
     <li><code>show_proj_icon</code> = yes/no.  Default 'yes'</li>
     <li><code>grid_view_tools</code> = git,hg,svn,tickets,wiki... Limit the tools shown in project list. Multivalue option (example grid_view_tools=git,wiki).  Default ''</li>
-    <li><code>show_download_button</code> = yes/no.  Default 'yes'</li>
+    <li><code>show_download_button</code> = yes/no.  Default 'no'</li>
 	<li><code>show_awards_banner</code> = yes/no.  Default 'yes'</li>
     <li><code>sort</code> = last_updated/alpha/random/last_registered.  Default 'last_updated'</li>
     <li><code>show_total</code> = yes/no.  Adds a sentence with a total count of how many projects are listed. Default 'no'</li>
diff --git a/Allura/allura/tests/test_globals.py b/Allura/allura/tests/test_globals.py
index f3adc87..0eb7723 100644
--- a/Allura/allura/tests/test_globals.py
+++ b/Allura/allura/tests/test_globals.py
@@ -493,14 +493,6 @@
         r = g.markdown_wiki.convert('[[projects display_mode=list columns=3]]')
         assert two_column_style not in r
 
-        # test project download button
-        r = g.markdown_wiki.convert(
-            '[[projects display_mode=list show_download_button=True]]')
-        assert 'download-button' in r
-        r = g.markdown_wiki.convert(
-            '[[projects display_mode=list show_download_button=False]]')
-        assert 'download-button' not in r
-
 
 @td.with_wiki
 def test_limit_tools_macro():
diff --git a/Allura/docs/extending.rst b/Allura/docs/extending.rst
index 7fb46da..c39d572 100644
--- a/Allura/docs/extending.rst
+++ b/Allura/docs/extending.rst
@@ -64,3 +64,44 @@
 * repo_cloned
 * repo_refreshed
 * repo_clone_task_failed
+
+
+Markdown Macros
+===============
+
+Most text inputs in Allura accept Markdown text which is parsed and turned into
+HTML before being rendered. The Markdown text may contain "macros" - custom
+commands which extend the Markdown language. Here's an example of a macro
+that comes with Allura::
+
+    [[project_admins]]
+
+Include this macro in a wiki page or other Markdown content, and when rendered
+it will be replaced by an actual list of the project's admin users.
+
+Extending Allura with your own macros is simple, requiring two basic steps:
+
+1. Decide on a name for your macro, then create a function with that name, and
+   decorate it with the `macro()` decorator from Allura. The function can
+   accept keyword arguments, and must return text or HTML. For example::
+
+    from allura.lib.macro import macro
+
+    @macro()
+    def hello(name='World'):
+        return "<p>Hello {}!</p>".format(name)
+
+2. Add an entry point for your macro to the `setup.py` for your package::
+
+    [allura.macros]
+    hello_macro = mypkg.mymodule:hello
+
+Note that the key name (`hello_macro` in this case) doesn't matter - the macro
+is named after the function name. Our example macro could be used in a couple
+ways::
+
+    [[hello]]
+    [[hello name=Universe]]
+
+For more help with macros, consult the source code for the macros that ship
+with Allura. You can find them in the `allura.lib.macro` package.