diff --git a/documentation/usage/assets.rst b/documentation/usage/assets.rst index caa758098..be1878f8d 100644 --- a/documentation/usage/assets.rst +++ b/documentation/usage/assets.rst @@ -15,7 +15,6 @@ The assets repository --------------------- Betty comes with an :py:mod:`Assets API ` that layers the assets provided by all the different components. -The order in which files are found: Each time an asset is needed, Betty finds it as follows: #. If the project provides the asset in its assets directory, use it @@ -25,34 +24,49 @@ Each time an asset is needed, Betty finds it as follows: This means that extensions can override Betty's default assets, and your projects can override both extensions' and Betty's assets. -The assets directory --------------------- -For each of Betty's default assets, extensions' assets, and your projects' assets, the assets directory follows the following structure: - -``./locale/`` - Contains assets for different locales. -``./locale/betty.pot`` - The gettext :doc:`translatable message ` catalog. -``./locale/$locale/betty.po`` - Where ``$locale`` is an `IETF BCP 47 language tag `_, ``betty.po`` is the gettext :doc:`translations ` file for that locale. -``./public/`` - Contains files that become part of your sites. -``./public/localized/`` - Contains files that will be localized when generating your sites. - - For sites with a single language, this effectively overrides ``./public/static``. - - On multilingual sites, these files end up in a subdirectory based on the locale they - are rendered in: ``./public/my-page.html.j2`` will be accessible on your site through - ``https://example.com/en/my-page.html`` for an English locale, for example. - - Examples of files that should be put here are any files that contain localizable (translatable) - content, which will likely be most, if not all of your HTML pages. -``./public/static/`` - Contains static files that become part of your sites. ``./public/my-file.txt`` will be - accessible on your site through ``https://example.com/my-file.txt``. - - Examples of files that should often be put here are CSS and JavaScript files, images for - your site's look and feel, and metadata files such as ``robots.txt`` and ``sitemap.xml``. -``./templates/`` - Contains (Jinja2) :doc:`templates `. +Assets directories +------------------ +For each of Betty's default assets, extensions' assets, and your projects' assets, the assets directory follows the +following structure: + +``locale/`` +^^^^^^^^^^^^^ +Contains assets for different locales. + +``locale/betty.pot`` +^^^^^^^^^^^^^^^^^^^^^^ +The gettext :doc:`translatable message ` catalog. + +``locale/$locale/betty.po`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Where ``$locale`` is an `IETF BCP 47 language tag `_, ``betty.po`` is the +gettext :doc:`translations ` file for that locale. + +``public/`` +^^^^^^^^^^^^^ +Contains files that become part of your sites. + +``public/localized/`` +^^^^^^^^^^^^^^^^^^^^^^^ +Contains files that will be localized when generating your sites. + +For sites with a single language, this effectively overrides ``public/static`` on a per-file basis. + +On multilingual sites, these files end up in a subdirectory based on the locale they are rendered in: +``public/localized/my-page.html.j2`` will be accessible on your site through ``https://example.com/en/my-page.html`` for +an English locale, for example. + +Examples of files that should be put here are any files that contain localizable (translatable) content, which will +likely be most, if not all of your HTML pages. + +``public/static/`` +^^^^^^^^^^^^^^^^^^^^ +Contains static files that become part of your sites. ``public/static/my-file.txt`` will be accessible on your site +through ``https://example.com/my-file.txt``. + +Examples of files that should often be put here are CSS and JavaScript files, images for your site's look and feel, and +metadata files such as ``robots.txt`` and ``sitemap.xml``. + +``templates/`` +^^^^^^^^^^^^^^^^ +Contains (Jinja2) :doc:`templates `.