Generating URLs
===============

Everything on the internal has a URL so it can be accessed publicly. The URLs for the various **resources** that Betty
published vary based on several factors, including but not limited to whether:

- the URL should be absolute or relative
- your site is multilingual
- your site uses :doc:`clean URLs </usage/project/configuration>`

How to generate URLs
--------------------

Python
^^^^^^

URLs are generated by calling the :py:meth:`betty.url.UrlGenerator.generate` method of any URL generator. In most cases,
you will want to use :py:attr:`betty.project.Project.url_generator`, which supports all project resources.

.. code-block:: python

    url_generator = await project.url_generator
    url_generator.generate(resource)

Jinja2 templates
^^^^^^^^^^^^^^^^

.. code-block:: jinja2

    resource | url

The :py:func:`url <betty.jinja2.filter.filter_url>` filter works almost identical to
:py:meth:`betty.url.UrlGenerator.generate`, except that it fills in some defaults from the Jinja2 environment, such as
the template's current locale and media type. This means that if you are rendering an HTML page, and want to link to
another HTML page in the same language, you will not need to provide this information explicitly.

Resources
---------

:py:attr:`betty.project.Project.url_generator` can generate URLs for the following types of resources:

Entities
^^^^^^^^

The URL for an entity points to its HTML page or JSON document.

Entity types
^^^^^^^^^^^^

The URL for an entity type points to the HTML page or JSON document containing the collection/listing of all entities of
that type.

``betty://`` URLs
^^^^^^^^^^^^^^^^^

To generate URLs to localized resources, such as arbitrary HTML pages, use resources that are strings starting with
``betty://``. For example, to generate a URL to ``/my/custom/page/index.html``, your resource becomes
``betty:///my/custom/page/index.html``.

The resource consists of the ``betty://`` prefix, and a root-relative path (with a leading slash). Note that the
resource contains **three** consecutive slashes.

``betty-static://`` URLs
^^^^^^^^^^^^^^^^^^^^^^^^

To generate URLs to static (unlocalized) resources, such as assets, use resources that are strings starting with
``betty-static://``. For example, to generate a URL to ``/my/custom.css``, your resource becomes
``betty-static:///my/custom.css``.

The resource consists of the ``betty-static://`` prefix, and a root-relative path (with a leading slash). Note that the
resource contains **three** consecutive slashes.

``betty-entity://`` URLs
^^^^^^^^^^^^^^^^^^^^^^^^

To generate URLs to entities when you do not have access to the entity directly, such as in configuration, use resources
that are strings starting with ``betty-entity://``. For example, to generate a URL to a person with ID ``jane-doe``,
your resource becomes ``betty-entity://person/jane-doe``.

The resource consists of the ``betty-static://`` prefix, the entity type ID, a slash, and the entity ID.