docs: add new UI docs:

- add ui-overview as UI toc page
- refactor ui-customization to top-level customizations page
- add template-guide for in-depth template reference
- add new-vue-ui page for docs on new ui, with images
- fix adding logo to old ui, add to docs

docs/code/pywb.apps.rst

@@ -1,74 +1,73 @@
-pywb\.apps package
+pywb.apps package
-==================
+=================
 
 Submodules
 ----------
 
-pywb\.apps\.cli module
+pywb.apps.cli module
-----------------------
+--------------------
 
 .. automodule:: pywb.apps.cli
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.frontendapp module
+pywb.apps.frontendapp module
-------------------------------
+----------------------------
 
 .. automodule:: pywb.apps.frontendapp
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.live module
+pywb.apps.live module
------------------------
+---------------------
 
 .. automodule:: pywb.apps.live
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.rewriterapp module
+pywb.apps.rewriterapp module
-------------------------------
+----------------------------
 
 .. automodule:: pywb.apps.rewriterapp
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.static\_handler module
+pywb.apps.static\_handler module
-----------------------------------
+--------------------------------
 
 .. automodule:: pywb.apps.static_handler
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.warcserverapp module
+pywb.apps.warcserverapp module
---------------------------------
+------------------------------
 
 .. automodule:: pywb.apps.warcserverapp
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.wayback module
+pywb.apps.wayback module
---------------------------
+------------------------
 
 .. automodule:: pywb.apps.wayback
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.apps\.wbrequestresponse module
+pywb.apps.wbrequestresponse module
-------------------------------------
+----------------------------------
 
 .. automodule:: pywb.apps.wbrequestresponse
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.indexer.rst

@@ -1,26 +1,25 @@
-pywb\.indexer package
+pywb.indexer package
-=====================
+====================
 
 Submodules
 ----------
 
-pywb\.indexer\.archiveindexer module
+pywb.indexer.archiveindexer module
-------------------------------------
+----------------------------------
 
 .. automodule:: pywb.indexer.archiveindexer
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.indexer\.cdxindexer module
+pywb.indexer.cdxindexer module
---------------------------------
+------------------------------
 
 .. automodule:: pywb.indexer.cdxindexer
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.manager.rst

@@ -1,42 +1,49 @@
-pywb\.manager package
+pywb.manager package
-=====================
+====================
 
 Submodules
 ----------
 
-pywb\.manager\.aclmanager module
+pywb.manager.aclmanager module
---------------------------------
+------------------------------
 
 .. automodule:: pywb.manager.aclmanager
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.manager\.autoindex module
+pywb.manager.autoindex module
--------------------------------
+-----------------------------
 
 .. automodule:: pywb.manager.autoindex
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.manager\.manager module
+pywb.manager.locmanager module
------------------------------
+------------------------------
+
+.. automodule:: pywb.manager.locmanager
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pywb.manager.manager module
+---------------------------
 
 .. automodule:: pywb.manager.manager
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.manager\.migrate module
+pywb.manager.migrate module
------------------------------
+---------------------------
 
 .. automodule:: pywb.manager.migrate
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.recorder.rst

@@ -1,42 +1,41 @@
-pywb\.recorder package
+pywb.recorder package
-======================
+=====================
 
 Submodules
 ----------
 
-pywb\.recorder\.filters module
+pywb.recorder.filters module
-------------------------------
+----------------------------
 
 .. automodule:: pywb.recorder.filters
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.recorder\.multifilewarcwriter module
+pywb.recorder.multifilewarcwriter module
-------------------------------------------
+----------------------------------------
 
 .. automodule:: pywb.recorder.multifilewarcwriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.recorder\.recorderapp module
+pywb.recorder.recorderapp module
-----------------------------------
+--------------------------------
 
 .. automodule:: pywb.recorder.recorderapp
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.recorder\.redisindexer module
+pywb.recorder.redisindexer module
------------------------------------
+---------------------------------
 
 .. automodule:: pywb.recorder.redisindexer
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.rewrite.rst

@@ -1,146 +1,145 @@
-pywb\.rewrite package
+pywb.rewrite package
-=====================
+====================
 
 Submodules
 ----------
 
-pywb\.rewrite\.content\_rewriter module
+pywb.rewrite.content\_rewriter module
----------------------------------------
+-------------------------------------
 
 .. automodule:: pywb.rewrite.content_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.cookie\_rewriter module
+pywb.rewrite.cookie\_rewriter module
---------------------------------------
+------------------------------------
 
 .. automodule:: pywb.rewrite.cookie_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.cookies module
+pywb.rewrite.cookies module
------------------------------
+---------------------------
 
 .. automodule:: pywb.rewrite.cookies
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.default\_rewriter module
+pywb.rewrite.default\_rewriter module
----------------------------------------
+-------------------------------------
 
 .. automodule:: pywb.rewrite.default_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.header\_rewriter module
+pywb.rewrite.header\_rewriter module
---------------------------------------
+------------------------------------
 
 .. automodule:: pywb.rewrite.header_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.html\_insert\_rewriter module
+pywb.rewrite.html\_insert\_rewriter module
---------------------------------------------
+------------------------------------------
 
 .. automodule:: pywb.rewrite.html_insert_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.html\_rewriter module
+pywb.rewrite.html\_rewriter module
-------------------------------------
+----------------------------------
 
 .. automodule:: pywb.rewrite.html_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.jsonp\_rewriter module
+pywb.rewrite.jsonp\_rewriter module
--------------------------------------
+-----------------------------------
 
 .. automodule:: pywb.rewrite.jsonp_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.regex\_rewriters module
+pywb.rewrite.regex\_rewriters module
---------------------------------------
+------------------------------------
 
 .. automodule:: pywb.rewrite.regex_rewriters
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.rewrite\_amf module
+pywb.rewrite.rewrite\_amf module
-----------------------------------
+--------------------------------
 
 .. automodule:: pywb.rewrite.rewrite_amf
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.rewrite\_dash module
+pywb.rewrite.rewrite\_dash module
------------------------------------
+---------------------------------
 
 .. automodule:: pywb.rewrite.rewrite_dash
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.rewrite\_hls module
+pywb.rewrite.rewrite\_hls module
-----------------------------------
+--------------------------------
 
 .. automodule:: pywb.rewrite.rewrite_hls
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.rewrite\_js\_workers module
+pywb.rewrite.rewrite\_js\_workers module
-------------------------------------------
+----------------------------------------
 
 .. automodule:: pywb.rewrite.rewrite_js_workers
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.rewriteinputreq module
+pywb.rewrite.rewriteinputreq module
--------------------------------------
+-----------------------------------
 
 .. automodule:: pywb.rewrite.rewriteinputreq
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.templateview module
+pywb.rewrite.templateview module
-----------------------------------
+--------------------------------
 
 .. automodule:: pywb.rewrite.templateview
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.url\_rewriter module
+pywb.rewrite.url\_rewriter module
------------------------------------
+---------------------------------
 
 .. automodule:: pywb.rewrite.url_rewriter
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.rewrite\.wburl module
+pywb.rewrite.wburl module
----------------------------
+-------------------------
 
 .. automodule:: pywb.rewrite.wburl
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.rst

@@ -5,6 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
+   :maxdepth: 4
 
    pywb.apps
    pywb.indexer
@@ -17,15 +18,14 @@ Subpackages
 Submodules
 ----------
 
-pywb\.version module
+pywb.version module
---------------------
+-------------------
 
 .. automodule:: pywb.version
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.utils.rst

@@ -1,82 +1,81 @@
-pywb\.utils package
+pywb.utils package
-===================
+==================
 
 Submodules
 ----------
 
-pywb\.utils\.binsearch module
+pywb.utils.binsearch module
------------------------------
+---------------------------
 
 .. automodule:: pywb.utils.binsearch
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.canonicalize module
+pywb.utils.canonicalize module
---------------------------------
+------------------------------
 
 .. automodule:: pywb.utils.canonicalize
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.format module
+pywb.utils.format module
---------------------------
+------------------------
 
 .. automodule:: pywb.utils.format
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.geventserver module
+pywb.utils.geventserver module
---------------------------------
+------------------------------
 
 .. automodule:: pywb.utils.geventserver
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.io module
+pywb.utils.io module
-----------------------
+--------------------
 
 .. automodule:: pywb.utils.io
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.loaders module
+pywb.utils.loaders module
----------------------------
+-------------------------
 
 .. automodule:: pywb.utils.loaders
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.memento module
+pywb.utils.memento module
----------------------------
+-------------------------
 
 .. automodule:: pywb.utils.memento
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.merge module
+pywb.utils.merge module
--------------------------
+-----------------------
 
 .. automodule:: pywb.utils.merge
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.utils\.wbexception module
+pywb.utils.wbexception module
--------------------------------
+-----------------------------
 
 .. automodule:: pywb.utils.wbexception
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.warcserver.index.rst

@@ -1,66 +1,65 @@
-pywb\.warcserver\.index package
+pywb.warcserver.index package
-===============================
+=============================
 
 Submodules
 ----------
 
-pywb\.warcserver\.index\.aggregator module
+pywb.warcserver.index.aggregator module
-------------------------------------------
+---------------------------------------
 
 .. automodule:: pywb.warcserver.index.aggregator
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.index\.cdxobject module
+pywb.warcserver.index.cdxobject module
------------------------------------------
+--------------------------------------
 
 .. automodule:: pywb.warcserver.index.cdxobject
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.index\.cdxops module
+pywb.warcserver.index.cdxops module
---------------------------------------
+-----------------------------------
 
 .. automodule:: pywb.warcserver.index.cdxops
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.index\.fuzzymatcher module
+pywb.warcserver.index.fuzzymatcher module
---------------------------------------------
+-----------------------------------------
 
 .. automodule:: pywb.warcserver.index.fuzzymatcher
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.index\.indexsource module
+pywb.warcserver.index.indexsource module
--------------------------------------------
+----------------------------------------
 
 .. automodule:: pywb.warcserver.index.indexsource
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.index\.query module
+pywb.warcserver.index.query module
--------------------------------------
+----------------------------------
 
 .. automodule:: pywb.warcserver.index.query
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.index\.zipnum module
+pywb.warcserver.index.zipnum module
---------------------------------------
+-----------------------------------
 
 .. automodule:: pywb.warcserver.index.zipnum
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.warcserver.resource.rst

@@ -1,42 +1,41 @@
-pywb\.warcserver\.resource package
+pywb.warcserver.resource package
-==================================
+================================
 
 Submodules
 ----------
 
-pywb\.warcserver\.resource\.blockrecordloader module
+pywb.warcserver.resource.blockrecordloader module
-----------------------------------------------------
+-------------------------------------------------
 
 .. automodule:: pywb.warcserver.resource.blockrecordloader
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.resource\.pathresolvers module
+pywb.warcserver.resource.pathresolvers module
-------------------------------------------------
+---------------------------------------------
 
 .. automodule:: pywb.warcserver.resource.pathresolvers
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.resource\.resolvingloader module
+pywb.warcserver.resource.resolvingloader module
---------------------------------------------------
+-----------------------------------------------
 
 .. automodule:: pywb.warcserver.resource.resolvingloader
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.resource\.responseloader module
+pywb.warcserver.resource.responseloader module
--------------------------------------------------
+----------------------------------------------
 
 .. automodule:: pywb.warcserver.resource.responseloader
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/code/pywb.warcserver.rst

@@ -1,10 +1,11 @@
-pywb\.warcserver package
+pywb.warcserver package
-========================
+=======================
 
 Subpackages
 -----------
 
 .. toctree::
+   :maxdepth: 4
 
    pywb.warcserver.index
    pywb.warcserver.resource
@@ -12,71 +13,70 @@ Subpackages
 Submodules
 ----------
 
-pywb\.warcserver\.access\_checker module
+pywb.warcserver.access\_checker module
-----------------------------------------
+--------------------------------------
 
 .. automodule:: pywb.warcserver.access_checker
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.amf module
+pywb.warcserver.amf module
-----------------------------
+--------------------------
 
 .. automodule:: pywb.warcserver.amf
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.basewarcserver module
+pywb.warcserver.basewarcserver module
----------------------------------------
+-------------------------------------
 
 .. automodule:: pywb.warcserver.basewarcserver
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.handlers module
+pywb.warcserver.handlers module
----------------------------------
+-------------------------------
 
 .. automodule:: pywb.warcserver.handlers
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.http module
+pywb.warcserver.http module
------------------------------
+---------------------------
 
 .. automodule:: pywb.warcserver.http
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.inputrequest module
+pywb.warcserver.inputrequest module
--------------------------------------
+-----------------------------------
 
 .. automodule:: pywb.warcserver.inputrequest
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.upstreamindexsource module
+pywb.warcserver.upstreamindexsource module
---------------------------------------------
+------------------------------------------
 
 .. automodule:: pywb.warcserver.upstreamindexsource
    :members:
    :undoc-members:
    :show-inheritance:
 
-pywb\.warcserver\.warcserver module
+pywb.warcserver.warcserver module
------------------------------------
+---------------------------------
 
 .. automodule:: pywb.warcserver.warcserver
    :members:
    :undoc-members:
    :show-inheritance:
 
-
 Module contents
 ---------------
 

docs/conf.py

@@ -53,7 +53,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'pywb'
-copyright = '2014-2020, Webrecorder Software, Rhizome, and Contributors'
+copyright = '2014-2021, Webrecorder Software, Rhizome, and Contributors'
 author = 'Ilya Kreymer'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -61,9 +61,9 @@ author = 'Ilya Kreymer'
 # built documents.
 #
 # The short X.Y version.
-version = '2.0'
+version = '2.7'
 # The full version, including alpha/beta/rc tags.
-release = '2.0'
+release = '2.7'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/manual/localization.rst

@@ -1,4 +1,4 @@
-.. _localizaation:
+.. _localization:
 
 Localization / Multi-lingual Support
 ------------------------------------

docs/manual/new-vue-ui.rst

@@ -0,0 +1,85 @@
+.. _new-vue-ui:
+
+
+New Vue-based UI (Alpha)
+========================
+
+With 2.7.0, pywb introduces a new `Vue UI <https://vuejs.org/>`_ based system, which can be enabled to provide a more feature-representation of a web archive.
+
+The UI consists of two parts, which can be enabled using the ``ui`` block in ``config.yaml``
+
+.. code::  yaml
+
+  ui:
+    vue_calendar_ui: true
+    vue_timeline_banner: true
+
+
+Note: This UI is still in development and not all features are operational yet.
+In particular, localization switching is not yet available in the alpha version.
+
+Overview
+--------
+
+Calendar UI
+^^^^^^^^^^^
+
+The new calendar UI provides a histogram and a clickable calendar representation of a web archive.
+
+The calendar is rendered in place of the standard URL query page.
+
+.. image:: images/vue-cal.png
+  :width: 600
+  :alt: Calendar UI Screenshot
+
+
+To enable this UI for URL query pages, set the ``ui.vue_calendar_ui`` property to true in the ``config.yaml``
+
+
+Banner Replay UI
+^^^^^^^^^^^^^^^^
+
+The new banner histogram allows for zooming in on captures per year as well as per month.
+
+Navigation preserves the different levels. The full calendar UI is also available as a dropdown by clicking the calendar icon.
+
+The new banner should allow for faster navigation across multiple captures.
+
+.. image:: images/vue-banner.png
+  :width: 600
+  :alt: Calendar UI Screenshot
+
+
+To enable this UI for replay pages, set the ``ui.vue_timeline_banner`` property to true in the ``config.yaml``
+
+
+Custom Logo
+^^^^^^^^^^^
+
+When using the custom banner, it is possible to configure a logo by setting ``ui.logo`` to a static file.
+
+If ommitted, the standard pywb logo will be used by default.
+
+
+Updating the Vue UI
+-------------------
+
+The UI is contained with the ``pywb/vueui`` directory.
+
+The Vue component sources can be found in ``pywb/vueui/src``.
+
+Updating the UI requires ``node`` and ``yarn``.
+
+To install and build, run:
+
+
+.. code:: console
+
+   cd pywb/vueui
+   yarn install
+   yarn build
+
+
+This will generate the output to ``pywb/static/vue/vueui.js`` which is loaded from the default templates when the Vue UI rendering is enabled.
+
+Additional styles for the banner are loaded from ``pywb/static/vue_banner.css``.

docs/manual/template-guide.rst

@@ -0,0 +1,360 @@
+.. _template-guide:
+
+Template Guide
+==============
+
+Introduction
+------------
+
+This guide provides a reference of all of the templates available in pywb and how they could be modified.
+
+These templates are found in the ``pywb/templates`` directory and can be overridden as needed, one HTML page at a time.
+
+Template variables are listed as ``{{ variable }}`` to indicate the syntax used for rendering the value of the variable in Jinja2.
+
+Copying a Template For Modification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To modify a template, it is often useful to start with the default template. To do so, simply copy a default template
+to a local ``templates`` directory.
+
+For convenience, you can also run: ``wb-manager template --add <template-name>`` to add the template automatically.
+
+For a list of available templates that can be overridden in this way, run ``wb-manager template --list``.
+
+
+Per-Collection Templates
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Certain templates can be customized per-collection, instead of for all of pywb.
+
+To override a template for a specific collection only, run ``wb-manager template --add <template-name> <coll-name>``
+
+For example:
+
+
+.. code:: console
+    
+    wb-manager init my-coll
+    wb-manager template --add search_html my-coll
+
+This will create the file ``collections/my-coll/templates/search.html``, a copy of the default search.html, but configured to be used only
+for the collection ``my-coll``.
+
+
+
+Base Templates (and supporting templates)
+-----------------------------------------
+
+File: ``base.html``
+
+This template includes the HTML added to all other pages, replay and non-replay. Shared JS and CSS includes can be added here.
+For themeing all pywb UI, it may be useful to modify this template.
+
+To customize the default pywb UI across multiple pages, the following additional templates
+can also be overriden:
+
+* ``head.html`` -- Template containing content to be added to the ``<head>`` of the ``base`` template
+
+* ``header.html`` -- Template to be added as the first content of the ``<body>`` tag of the ``base`` template
+
+* ``footer.html`` -- Template for adding content as the "footer" of the ``<body>`` tag of the ``base`` template
+
+
+The ``base.html`` template also provides five blocks that can be supplied by templates that extend it.
+
+* ``title`` -- Block for supplying the title for the page
+
+* ``head`` -- Block for adding content to the ``<head>``, includes ``head.html`` template
+
+* ``header`` -- Block for adding content to the ``<body>`` before the ``body`` block, includes the ``header.html`` template
+
+* ``body`` -- Block for adding the primary content to template
+
+* ``footer`` -- Block for adding content to the ``<body>`` after the ``body`` block, includes the ``footer.html`` template
+
+
+Home, Collection and Search Templates
+-------------------------------------
+
+
+Home Page Template
+^^^^^^^^^^^^^^^^^^
+
+File: ``index.html``
+
+This template renders the home page for pywb, and by default renders a list of available collections.
+
+
+Template variables:
+
+* ``{{ routes }}`` - a list of available collection routes.
+
+* ``{{ all_metadata }}`` - a dictionary of all metadata for all collections, keyed by collection id. See :ref:`custom-metadata` for more info on the custom metadata.
+
+
+Additionally, the :ref:`shared-template-vars` are also available to the home page template, as well as all other templates.
+
+
+Collection Page Template
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+File: ``search.html``
+
+The 'collection page' template is the page rendered when no URL is specified, eg. ``http://localhost:8080/my-collection/``.
+
+The default template renders a search page that can be used to start searching for URLs.
+
+Template variables:
+
+* ``{{ coll }}`` - the collection name identifier.
+
+* ``{{ metadata }}`` - an optional dictionary of metadata. See :ref:`custom-metadata` for more info.
+
+* ``{{ ui }}`` - an optional ``ui`` dictionary from ``config.yaml``, if any
+
+
+.. _custom-metadata:
+
+Custom Metadata
+"""""""""""""""
+
+If custom collection metadata is provided, this page will automatically show this metadata as well.
+
+It is possible to also add custom metadata per-collection that will be available to the collection.
+
+For dynamic collections, any fields placed under ``<coll_name>/metadata.yaml`` filed can be accessed
+
+via the ``{{ metadata }}`` variable.
+
+For example, if metadata file contains:
+
+.. code:: yaml
+
+    somedata: value
+
+Accessing ``{{ metadata.somedata }}`` will resolve to ``value``
+
+The metadata can also be added via commandline: ``wb-manager metadata myCollection --set somedata=value]``
+
+
+URL Query/Calendar Page Template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+File: ``query.html``
+
+This template is rendered for any URL search response pages, either a single URL or more complex queries.
+
+For example, the page ``http://localhost:8080/my-collection/*/https://example.com/`` will be rendered using this template.
+
+The default template supports the standard pywb table view, as well as a conditional new vue-based UI. (See :ref:`new-vue-ui` for more info on the new UI)
+
+Template variables:
+
+* ``{{ url }}`` - the URL being queried, eg. ``https://example.com/``
+
+* ``{{ prefix }}`` - the collection prefix that will be used for replay, eg. ``http://localhost:8080/my-collection/``
+
+* ``{{ ui }}`` - an optional ``ui`` dictionary from ``config.yaml``, if any
+
+* ``{{ static_prefix }}`` - the prefix from which static files will be accessed from, eg. ``http://localhost:8080/static/``
+
+
+Replay and Banner Templates
+---------------------------
+
+The following templates are used to configure the replay view itself.
+
+
+Banner Template
+^^^^^^^^^^^^^^^
+
+File: ``banner.html``
+
+This template is used to render the banner and is used both in framed replay and frameless replay.
+
+In framed replay, the template is only rendered in the top/outer frame, while in frameless replay,
+it is added to every page.
+
+Template variables:
+
+* ``{{ url }}`` - the URL being replayed.
+
+* ``{{ timestamp }}`` - the timestamp being replayed, eg. ``20211226`` in ``http://localhost:8080/pywb/20211226/mp_/https://example.com/``
+
+* ``{{ is_framed }}`` - true/false if currently in framed mode.
+
+* ``{{ wb_prefix }}`` - the collection prefix, eg. ``http://localhost:8080/pywb/``
+
+* ``{{ config }}`` - provides the contents of the ``config.yaml`` as a dictionary.
+
+* ``{{ ui }}`` - an optional ``ui`` dictionary from ``config.yaml``, if any.
+
+
+The default banner creates all UI dynamically via JS. However, a custom banner could also insert HTML to render the banner directly.
+
+By default, the banner checks the ``{{ ui.vue_timeline_banner }}`` and renders the new UI or the standard default UI.
+
+The default UI is created via the ``default_banner.js`` script.
+
+See :ref:`new-vue-ui` for more details on the new Vue UI.
+
+
+Head Insert Template
+^^^^^^^^^^^^^^^^^^^^
+
+File: ``head_insert.html``
+
+This template represents the HTML injected into every replay page to add support for client-side rewriting via ``wombat.js``.
+
+This template is part of the core pywb replay, and modifying this template is not recommended. 
+
+For customizing the banner, modify the ``banner.html`` template instead.
+
+
+Top Frame Template
+^^^^^^^^^^^^^^^^^^
+
+File: ``frame_insert.html``
+
+This template represents the top-level frame that is inserted to render the replay in framed mode.
+
+By design, this template does *not* extend from the base template.
+
+This template is responsible for creating the iframe that will render the content.
+
+This template only renders the banner and is designed *not* to set the encoding to allow the browser to 'detect' the encoding for the containing iframe.
+For this reason, the template should only contain ASCII text, and %-encode any non-ASCII characters.
+
+Template variables:
+
+* ``{{ url }}`` - the URL being replayed.
+
+* ``{{ wb_url }}`` - A complete ``WbUrl`` object, which contains the ``url``, ``timestamp`` and ``mod`` properties, representing the replay url.
+
+* ``{{ is_framed }}`` - true/false if currently in framed mode.
+
+* ``{{ wb_prefix }}`` - the collection prefix, eg. ``http://localhost:8080/pywb/``
+
+
+
+.. _custom-top-frame:
+
+Customizing the Top Frame Template
+""""""""""""""""""""""""""""""""""
+
+The top-frame used for framed replay can be replaced or augmented
+by modifying the ``frame_insert.html``.
+
+To start with modifying the default outer page, you can add it to the current
+templates directory by running ``wb-manager template --add frame_insert_html``
+
+To initialize the replay, the outer page should include ``wb_frame.js``,
+create an ``<iframe>`` element and pass the id (or element itself) to the ``ContentFrame`` constructor:
+
+.. code-block:: html
+
+  <script src='{{ host_prefix }}/{{ static_path }}/wb_frame.js'> </script>
+  <script>
+  var cframe = new ContentFrame({"url": "{{ url }}" + window.location.hash,
+                                 "prefix": "{{ wb_prefix }}",
+                                 "request_ts": "{{ wb_url.timestamp }}",
+                                 "iframe": "#replay_iframe"});
+  </script>
+
+
+The outer frame can receive notifications of changes to the replay via ``postMessage``
+
+For example, to detect when the content frame changed and log the new url and timestamp,
+use the following script to the outer frame html:
+
+.. code-block:: javascript
+
+  window.addEventListener("message", function(event) {
+    if (event.data.wb_type == "load" || event.data.wb_type == "replace-url") {
+      console.log("New Url: " + event.data.url);
+      console.log("New Timestamp: " + event.data.ts);
+    }
+  });
+
+The ``load`` message is sent when a new page is first loaded, while ``replace-url`` is used
+for url changes caused by content frame History navigation.
+
+
+Error Templates
+---------------
+
+The following templates are used to render errors.
+
+
+Page Not Found Template
+^^^^^^^^^^^^^^^^^^^^^^^
+
+File: ``not_found.html`` - template for 404 error pages.
+
+This template is used to render any 404/page not found errors that can occur when loading a URL that is not in the web archive.
+
+Template variables:
+
+* ``{{ url }}`` - the URL of the page
+
+* ``{{ wbrequest }}`` - the full ``WbRequest`` object which can be used to get additional info about the request.
+
+
+(The default template checks ``{{ wbrequest and wbrequest.env.pywb_proxy_magic }}`` to determine if the request is via an :ref:`https-proxy` connection or a regular request).
+
+
+Generic Error Template
+^^^^^^^^^^^^^^^^^^^^^^
+
+File: ``error.html`` - generic error template.
+
+
+This template is used to render all other errors that are not 'page not found'.
+
+Template variables:
+
+*  ``{{ err_msg }}`` - a shorter error message indicating what went wrong.
+
+*  ``{{ err_details }}`` - additional details about the error.
+
+
+
+
+.. _shared-template-vars:
+
+Shared Template Variables
+-------------------------
+
+The following template variables are available to all templates.
+
+* ``{{ env }}`` - contains environment variables passed to pywb.
+
+* ``{{ env.pywb_proxy_magic }}`` - if set, indicates pywb is accessed via proxy. See :ref:`https-proxy`
+
+* ``{{ static_prefix }}`` - path to use for loading static files.
+
+
+UI Configuration
+^^^^^^^^^^^^^^^^
+
+Starting with pywb 2.7.0, the ``ui`` block in ``config.yaml`` can contain any custom ui-specific settings.
+
+This block is provided to the ``search.html``, ``query.html`` and ``banner.html`` templates.
+
+
+Localization Globals
+^^^^^^^^^^^^^^^^^^^^
+
+The Localization system (see: :ref:`localization`) adds several additional template globals, to faciliate listing available locales and getting URLs to switch locales, including:
+
+* ``{{ _Q() }}`` - a function used to mark certain text for localization, eg. ``{{ _Q('localize this text') }}``
+
+* ``{{ env.pywb_lang }}`` - indicates current locale language code used for localization.
+
+* ``{{ locales }}`` - a list of all available locale language codes, used for iterating over all locales.
+
+* ``{{ get_locale_prefixes() }}`` - a function which returns the prefixes to use to switch locales.
+
+* ``{{ switch_locale() }}`` - a function used to render a URL to switch locale for the current page. Ex: ``<a href="{{ switch_locale(locale) }}">{{ locale }}</a>`` renders a link to switch to a specific locale.
+

docs/manual/ui-customization.rst

@@ -1,141 +1,9 @@
-.. _ui-customizations:
+UI Customization
+================
 
-UI Customizations
+.. toctree::
------------------
 
-pywb supports UI customizations, either for an entire archive,
+   ui-guide
-or per-collection. Jinja2 templates are used for rendering all views,
+   new-vue-ui
-and static files can also be added as needed.
+   template-guide
  
-Templates
-^^^^^^^^^
-
-Default templates, listed below, are found in the ``./pywb/templates/`` directory.
-
-Custom template files placed in the ``templates`` directory, either in the root or per collection, will override that template.
-
-To copy the default pywb template to the template directory using the cli tools, run:
-
-``wb-manager template --add search_html``
-
-The following page-level templates are available, corresponding to home page, collection page or search results:
-
- * ``index.html`` -- Home Page Template, used for ``http://my-archive.example.com/``
-
- * ``search.html`` -- Collection Template, used for each collection page ``http://my-archive.example.com/<coll name>/``
-
- * ``query.html`` -- Capture Query Page for a given url, used for ``http://my-archive.example.com/<coll name/*/<url>``
-
-Error Pages:
-
- * ``not_found.html`` -- Page to show when a url is not found in the archive
-
- * ``error.html`` -- Generic Error Page for any error (except not found)
-
-Replay and Banner templates:
-
- * ``frame_insert.html`` -- Top-frame for framed replay mode (not used with frameless mode)
-
- * ``head_insert.html`` -- Rewriting code injected into ``<head>`` of each replayed page.
-   This template includes the banner template and itself should generally not need to be modified.
-
- * ``banner.html`` -- The banner used for frameless replay. Can be set to blank to disable the banner.
-
-
-To customize the default pywb UI across multiple pages, the following generic templates
-can also be overriden:
-
-* ``base.html`` -- The base template used for non-replay related pages.
-
-* ``head.html`` -- Template containing content to be added to the ``<head>`` of the ``base`` template
-
-* ``header.html`` -- Template to be added as the first content of the ``<body>`` tag of the ``base`` template
-
-* ``footer.html`` -- Template for adding content as the "footer" of the ``<body>`` tag of the ``base`` template
-
-
-The ``base.html`` template also provides five blocks that can be supplied by templates that extend it.
-
-* ``title`` -- Block for supplying the title for the page
-
-* ``head`` -- Block for adding content to the ``<head>``, includes ``head.html`` template
-
-* ``header`` -- Block for adding content to the ``<body>`` before the ``body`` block, includes the ``header.html`` template
-
-* ``body`` -- Block for adding the primary content to template
-
-* ``footer`` -- Block for adding content to the ``<body>`` after the ``body`` block, includes the ``footer.html`` template
-
-Static Files
-^^^^^^^^^^^^
-
-The pywb server will automatically support static files placed under the following directories:
-
-* Files under the root ``static`` directory can be accessed via ``http://my-archive.example.com/static/<filename>``
-
-* Files under the per-collection ``./collections/<coll name>/static`` directory can be accessed via ``http://my-archive.example.com/static/_/<coll name>/<filename>``
-
-
-Custom Metadata
-^^^^^^^^^^^^^^^
-
-It is possible to also add custom metadata that will be available in the Jinja2 template.
-
-For dynamic collections, any fields placed under ``<coll_name>/metadata.yaml`` filed can be accessed
-
-via the ``{{ metadata }}`` variable.
-
-For example, if metadata file contains:
-
-.. ex-block:: yaml
-
-    somedata: value
-
-Accessing ``{{ metadata.somedata }}`` will resolve to ``value``
-
-The metadata can also be added via commandline: ``wb-manager metadata myCollection --set somedata=value]``
-
-
-
-The default collection UI template (search.html) currently lists all of the available metadata fields.
-
-
-Custom Outer Replay Frame
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The top-frame used for framed replay can be replaced or augmented
-by modifying the ``frame_insert.html``.
-
-To start with modifying the default outer page, you can add it to the current
-templates directory by running ``wb-manager template --add frame_insert_html``
-
-To initialize the replay, the outer page should include ``wb_frame.js``,
-create an ``<iframe>`` element and pass the id (or element itself) to the ``ContentFrame`` constructor:
-
-.. code-block:: html
-
-  <script src='{{ host_prefix }}/{{ static_path }}/wb_frame.js'> </script>
-  <script>
-  var cframe = new ContentFrame({"url": "{{ url }}" + window.location.hash,
-                                 "prefix": "{{ wb_prefix }}",
-                                 "request_ts": "{{ wb_url.timestamp }}",
-                                 "iframe": "#replay_iframe"});
-  </script>
-
-
-The outer frame can receive notifications of changes to the replay via ``postMessage``
-
-For example, to detect when the content frame changed and log the new url and timestamp,
-use the following script to the outer frame html:
-
-.. code-block:: javascript
-
-  window.addEventListener("message", function(event) {
-    if (event.data.wb_type == "load" || event.data.wb_type == "replace-url") {
-      console.log("New Url: " + event.data.url);
-      console.log("New Timestamp: " + event.data.ts);
-    }
-  });
-
-The ``load`` message is sent when a new page is first loaded, while ``replace-url`` is used
-for url changes caused by content frame History navigation.

docs/manual/ui-guide.rst

@@ -0,0 +1,116 @@
+.. _ui-customizations:
+
+Customization Guide
+===================
+
+Most aspects of the pywb user-interface can be customized by changing the default styles, or overriding the HTML templates.
+
+This guide covers a few different options for customizing the UI.
+
+
+Changing the Default Styles
+---------------------------
+
+When using the default UI, pywb styles can be configured in ``pywb/static/default_banner.css``
+
+The stylesheet contained under ``#_wb_frame_top_banner`` affect the rendering of the default banner in framed mode.
+
+
+Configuring a Logo
+------------------
+
+An optional logo can be configured at the top-left of the default banner.
+
+To enable the logo set the ``ui.logo`` property in ``config.yaml`` to point to the URL of the logo.
+
+The URL can be any image URL, including a URL served from static directory.
+
+For example, to add the default pywb logo to the banner, use the following to the config:
+
+.. code:: yaml
+
+    ui:
+        logo: /static/pywb-logo-sm.png
+
+
+New Vue-based UI (Alpha)
+------------------------
+
+With pywb 2.7.0, pywb includes a brand new UI which includes a visual calendar mode and a histogram-based banner.
+
+See :ref:`new-vue-ui` for more information on how to enable this UI.
+
+
+Customizing UI Templates
+------------------------
+
+pywb renders HTML using the Jinja2 templating engine, loading default templates from the ``pywb/templates`` directory.
+
+If running from a custom directory, templates can be placed in the ``templates`` directory and will override the defaults.
+
+See :ref:`template-guide` for more details on customizing the templates.
+
+
+Static Files
+------------
+
+pywb will automatically support static files placed under the following directories:
+
+* Files under the root ``static`` directory: ``static/my-file.js`` can be accessed via ``http://localhost:8080/static/my-file.js``
+
+
+* Files under the per-collection directory: ``./collections/my-coll/static/my-file.js`` can be accessed via ``http://localhost:8080/pywb/static/_/my-coll/my-file.js``
+
+
+It is possible to change these settings via ``config.yaml``:
+
+* ``static_prefix`` - sets the URL path used in pywb to serve static content (default ``static``)
+
+* ``static_dir`` - sets the directory name used to read static files (default ``static``)
+
+While pywb can serve static files, it is recommended to use an existing web server to serve static files, especially if already using it in production.
+
+For example, this can be done via nginx with:
+
+
+.. code:: text
+
+    location /wayback/static {
+        alias /pywb/pywb/static;
+    }
+
+
+Loading Custom Metadata
+-----------------------
+
+pywb includes a default mechanism for loading externally defined metadata, loaded from a per-collection ``metadata.yaml`` YAML file at runtime.
+
+See :ref:`custom-metadata` for more details.
+
+Additionally, the banner template has access to the contents of the ``config.yaml`` via the ``{{ config }}`` template variable,
+allowing for passing in arbitrary config information.
+
+For more dynamic loading of data, the banner and all of the templates can load additional data via JS ``fetch()`` calls.
+
+
+Embedding pywb in frames
+------------------------
+
+It should be possible to embed pywb replay itself as an iframe as needed.
+
+For customizing the top-level page and banner, see :ref:`custom-top-frame`.
+
+However, there may be other reasons to embed pywb in an iframe.
+
+This can be doen simply by including something like:
+
+.. code:: html
+
+   <html>
+     <head>
+       <body>
+         <div>Embedding pywb replay</div>
+         <iframe style="width: 100%; height: 100%" src="http://localhost:8080/pywb/20130729195151/http://test@example.com/"></iframe>
+      </body>
+   </html>
+

pywb/templates/banner.html

@@ -19,7 +19,7 @@ window.banner_info = {
     prefix: "{{ wb_prefix }}",
     staticPrefix: "{{ static_prefix }}",
 
-    logo: "{{ ui.logo }}"
+    logoImg: "{{ ui.logo }}"
 };
 </script>