mirror
/
wagtail
kopia lustrzana https://github.com/wagtail/wagtail
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność

Add headings for all settings

pull/7225/head
Thibaud Colas 2021-06-28 10:22:39 +01:00
rodzic 3ee060ffd7
commit 86b84a2010
1 zmienionych plików z 187 dodań i 0 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

187
docs/reference/settings.rst
Wyświetl plik

@ -7,6 +7,9 @@ Wagtail makes use of the following settings, in addition to :doc:`Django's core
Site Name
=========
``WAGTAIL_SITE_NAME``
---------------------
.. code-block:: python
WAGTAIL_SITE_NAME = 'Stark Industries Skunkworks'
@ -18,6 +21,9 @@ This is the human-readable name of your Wagtail install which welcomes users upo
Append Slash
============
``WAGTAIL_APPEND_SLASH``
------------------------
.. code-block:: python
# Don't add a trailing slash to Wagtail-served URLs
@ -38,6 +44,9 @@ When ``WAGTAIL_APPEND_SLASH`` is ``False``, requests to Wagtail pages will be se
Search
======
``WAGTAILSEARCH_BACKENDS``
--------------------------
.. code-block:: python
WAGTAILSEARCH_BACKENDS = {
@ -49,6 +58,9 @@ Search
Define a search backend. For a full explanation, see :ref:`wagtailsearch_backends`.
``WAGTAILSEARCH_RESULTS_TEMPLATE``, ``WAGTAILSEARCH_RESULTS_TEMPLATE_AJAX``
---------------------------------------------------------------------------
.. code-block:: python
WAGTAILSEARCH_RESULTS_TEMPLATE = 'myapp/search_results.html'
@ -58,6 +70,9 @@ Override the templates used by the search front-end views.
.. _wagtailsearch_hits_max_age:
``WAGTAILSEARCH_HITS_MAX_AGE``
------------------------------
.. code-block:: python
WAGTAILSEARCH_HITS_MAX_AGE = 14
@ -160,6 +175,9 @@ Wagtail has a builtin list of the most common providers.
The embeds fetching can be fully configured using the ``WAGTAILEMBEDS_FINDERS``
setting. This is fully documented in :ref:`configuring_embed_finders`.
``WAGTAILEMBEDS_RESPONSIVE_HTML``
---------------------------------
.. code-block:: python
WAGTAILEMBEDS_RESPONSIVE_HTML = True
@ -170,12 +188,17 @@ to assist in making them responsive. See :ref:`responsive-embeds` for details.
Dashboard
=========
``WAGTAILADMIN_RECENT_EDITS_LIMIT``
-----------------------------------
.. code-block:: python
WAGTAILADMIN_RECENT_EDITS_LIMIT = 5
This setting lets you change the number of items shown at 'Your most recent edits' on the dashboard.
``WAGTAILADMIN_USER_LOGIN_FORM``
--------------------------------
.. code-block:: python
@ -186,6 +209,9 @@ Allows the default ``LoginForm`` to be extended with extra fields.
.. _wagtail_gravatar_provider_url:
``WAGTAIL_GRAVATAR_PROVIDER_URL``
---------------------------------
.. code-block:: python
WAGTAIL_GRAVATAR_PROVIDER_URL = '//www.gravatar.com/avatar'
@ -194,6 +220,9 @@ If a user has not uploaded a profile picture, Wagtail will look for an avatar li
.. _wagtail_moderation_enabled:
``WAGTAIL_MODERATION_ENABLED``
------------------------------
.. code-block:: python
WAGTAIL_MODERATION_ENABLED = True
@ -205,6 +234,9 @@ Comments
.. versionadded:: 2.13
``WAGTAILADMIN_COMMENTS_ENABLED``
---------------------------------
.. code-block:: python
# Disable commenting
@ -215,12 +247,17 @@ Sets whether commenting is enabled for pages (``True`` by default).
Images
======
``WAGTAILIMAGES_IMAGE_MODEL``
-----------------------------
.. code-block:: python
WAGTAILIMAGES_IMAGE_MODEL = 'myapp.MyImage'
This setting lets you provide your own image model for use in Wagtail, which should extend the built-in ``AbstractImage`` class.
``WAGTAILIMAGES_IMAGE_FORM_BASE``
---------------------------------
.. code-block:: python
@ -229,6 +266,8 @@ This setting lets you provide your own image model for use in Wagtail, which sho
This setting lets you provide your own image base form for use in Wagtail, which might extend the built-in ``BaseImageForm`` class or replace it entirely.
You can use it to specify or override the widgets to use in the admin form.
``WAGTAILIMAGES_MAX_UPLOAD_SIZE``
---------------------------------
.. code-block:: python
@ -236,30 +275,45 @@ You can use it to specify or override the widgets to use in the admin form.
This setting lets you override the maximum upload size for images (in bytes). If omitted, Wagtail will fall back to using its 10MB default value.
``WAGTAILIMAGES_MAX_IMAGE_PIXELS``
----------------------------------
.. code-block:: python
WAGTAILIMAGES_MAX_IMAGE_PIXELS = 128000000 # i.e. 128 megapixels
This setting lets you override the maximum number of pixels an image can have. If omitted, Wagtail will fall back to using its 128 megapixels default value. The pixel count takes animation frames into account - for example, a 25-frame animation of size 100x100 is considered to have 100 * 100 * 25 = 250000 pixels.
``WAGTAILIMAGES_FEATURE_DETECTION_ENABLED``
-------------------------------------------
.. code-block:: python
WAGTAILIMAGES_FEATURE_DETECTION_ENABLED = True
This setting enables feature detection once OpenCV is installed, see all details on the :ref:`image_feature_detection` documentation.
``WAGTAILIMAGES_INDEX_PAGE_SIZE``
---------------------------------
.. code-block:: python
WAGTAILIMAGES_INDEX_PAGE_SIZE = 20
Specifies the number of images per page shown on the main Images listing in the Wagtail admin.
``WAGTAILIMAGES_USAGE_PAGE_SIZE``
---------------------------------
.. code-block:: python
WAGTAILIMAGES_USAGE_PAGE_SIZE = 20
Specifies the number of items per page shown when viewing an image's usage (see :ref:`WAGTAIL_USAGE_COUNT_ENABLED <WAGTAIL_USAGE_COUNT_ENABLED>`).
``WAGTAILIMAGES_CHOOSER_PAGE_SIZE``
-----------------------------------
.. code-block:: python
WAGTAILIMAGES_CHOOSER_PAGE_SIZE = 12
@ -269,12 +323,17 @@ Specifies the number of images shown per page in the image chooser modal.
Documents
=========
``WAGTAILDOCS_DOCUMENT_MODEL``
------------------------------
.. code-block:: python
WAGTAILDOCS_DOCUMENT_MODEL = 'myapp.MyDocument'
This setting lets you provide your own document model for use in Wagtail, which should extend the built-in ``AbstractDocument`` class.
``WAGTAILDOCS_DOCUMENT_FORM_BASE``
----------------------------------
.. code-block:: python
@ -286,6 +345,9 @@ You can use it to specify or override the widgets to use in the admin form.
.. _wagtaildocs_serve_method:
``WAGTAILDOCS_SERVE_METHOD``
----------------------------
.. code-block:: python
WAGTAILDOCS_SERVE_METHOD = 'redirect'
@ -302,6 +364,9 @@ If ``WAGTAILDOCS_SERVE_METHOD`` is unspecified or set to ``None``, the default m
.. _wagtaildocs_content_types:
``WAGTAILDOCS_CONTENT_TYPES``
-----------------------------
.. code-block:: python
WAGTAILDOCS_CONTENT_TYPES = {
@ -313,6 +378,9 @@ Specifies the MIME content type that will be returned for the given file extensi
.. _wagtaildocs_inline_content_types:
``WAGTAILDOCS_INLINE_CONTENT_TYPES``
------------------------------------
.. code-block:: python
WAGTAILDOCS_INLINE_CONTENT_TYPES = ['application/pdf', 'text/plain']
@ -321,6 +389,9 @@ A list of MIME content types that will be shown inline in the browser (by servin
.. _wagtaildocs_extensions:
``WAGTAILDOCS_EXTENSIONS``
--------------------------
.. code-block:: python
WAGTAILDOCS_EXTENSIONS = ['pdf', 'docx']
@ -333,30 +404,45 @@ be renamed to have an extension no matter what data they contain.
Password Management
===================
``WAGTAIL_PASSWORD_MANAGEMENT_ENABLED``
---------------------------------------
.. code-block:: python
WAGTAIL_PASSWORD_MANAGEMENT_ENABLED = True
This specifies whether users are allowed to change their passwords (enabled by default).
``WAGTAIL_PASSWORD_RESET_ENABLED``
----------------------------------
.. code-block:: python
WAGTAIL_PASSWORD_RESET_ENABLED = True
This specifies whether users are allowed to reset their passwords. Defaults to the same as ``WAGTAIL_PASSWORD_MANAGEMENT_ENABLED``. Password reset emails will be sent from the address specified in Django's ``DEFAULT_FROM_EMAIL`` setting.
``WAGTAILUSERS_PASSWORD_ENABLED``
---------------------------------
.. code-block:: python
WAGTAILUSERS_PASSWORD_ENABLED = True
This specifies whether password fields are shown when creating or editing users through Settings -> Users (enabled by default). Set this to False (along with ``WAGTAIL_PASSWORD_MANAGEMENT_ENABLED`` and ``WAGTAIL_PASSWORD_RESET_ENABLED``) if your users are authenticated through an external system such as LDAP.
``WAGTAILUSERS_PASSWORD_REQUIRED``
----------------------------------
.. code-block:: python
WAGTAILUSERS_PASSWORD_REQUIRED = True
This specifies whether password is a required field when creating a new user. True by default; ignored if ``WAGTAILUSERS_PASSWORD_ENABLED`` is false. If this is set to False, and the password field is left blank when creating a user, then that user will have no usable password; in order to log in, they will have to reset their password (if ``WAGTAIL_PASSWORD_RESET_ENABLED`` is True) or use an alternative authentication system such as LDAP (if one is set up).
``WAGTAIL_EMAIL_MANAGEMENT_ENABLED``
------------------------------------
.. code-block:: python
WAGTAIL_EMAIL_MANAGEMENT_ENABLED = True
@ -368,18 +454,27 @@ This specifies whether users are allowed to change their email (enabled by defau
Email Notifications
===================
``WAGTAILADMIN_NOTIFICATION_FROM_EMAIL``
----------------------------------------
.. code-block:: python
WAGTAILADMIN_NOTIFICATION_FROM_EMAIL = 'wagtail@myhost.io'
Wagtail sends email notifications when content is submitted for moderation, and when the content is accepted or rejected. This setting lets you pick which email address these automatic notifications will come from. If omitted, Wagtail will fall back to using Django's ``DEFAULT_FROM_EMAIL`` setting if set, or ``webmaster@localhost`` if not.
``WAGTAILADMIN_NOTIFICATION_USE_HTML``
--------------------------------------
.. code-block:: python
WAGTAILADMIN_NOTIFICATION_USE_HTML = True
Notification emails are sent in `text/plain` by default, change this to use HTML formatting.
``WAGTAILADMIN_NOTIFICATION_INCLUDE_SUPERUSERS``
------------------------------------------------
.. code-block:: python
WAGTAILADMIN_NOTIFICATION_INCLUDE_SUPERUSERS = False
@ -391,6 +486,9 @@ Notification emails are sent to moderators and superusers by default. You can ch
Wagtail update notifications
============================
``WAGTAIL_ENABLE_UPDATE_CHECK``
-------------------------------
.. code-block:: python
WAGTAIL_ENABLE_UPDATE_CHECK = True
@ -401,12 +499,18 @@ For admins only, Wagtail performs a check on the dashboard to see if newer relea
Private pages / documents
=========================
``PASSWORD_REQUIRED_TEMPLATE``
------------------------------
.. code-block:: python
PASSWORD_REQUIRED_TEMPLATE = 'myapp/password_required.html'
This is the path to the Django template which will be used to display the "password required" form when a user accesses a private page. For more details, see the :ref:`private_pages` documentation.
``DOCUMENT_PASSWORD_REQUIRED_TEMPLATE``
---------------------------------------
.. code-block:: python
DOCUMENT_PASSWORD_REQUIRED_TEMPLATE = 'myapp/document_password_required.html'
@ -416,12 +520,18 @@ As above, but for password restrictions on documents. For more details, see the
Login page
==========
``WAGTAIL_FRONTEND_LOGIN_TEMPLATE``
-----------------------------------
The basic login page can be customised with a custom template.
.. code-block:: python
WAGTAIL_FRONTEND_LOGIN_TEMPLATE = 'myapp/login.html'
``WAGTAIL_FRONTEND_LOGIN_URL``
------------------------------
Or the login page can be a redirect to an external or internal URL.
.. code-block:: python
@ -433,6 +543,9 @@ For more details, see the :ref:`login_page` documentation.
Case-Insensitive Tags
=====================
``TAGGIT_CASE_INSENSITIVE``
---------------------------
.. code-block:: python
TAGGIT_CASE_INSENSITIVE = True
@ -442,6 +555,9 @@ Tags are case-sensitive by default ('music' and 'Music' are treated as distinct
Multi-word tags
===============
``TAG_SPACES_ALLOWED``
----------------------
.. code-block:: python
TAG_SPACES_ALLOWED = False
@ -451,6 +567,9 @@ Tags can only consist of a single word, no spaces allowed. The default setting i
Tag limit
=========
``TAG_LIMIT``
-------------
.. code-block:: python
TAG_LIMIT = 5
@ -460,6 +579,9 @@ Limit the number of tags that can be added to (django-taggit) Tag model. Default
Unicode Page Slugs
==================
``WAGTAIL_ALLOW_UNICODE_SLUGS``
-------------------------------
.. code-block:: python
WAGTAIL_ALLOW_UNICODE_SLUGS = True
@ -471,6 +593,9 @@ By default, page slugs can contain any alphanumeric characters, including non-La
Auto update preview
===================
``WAGTAIL_AUTO_UPDATE_PREVIEW``
-------------------------------
.. code-block:: python
WAGTAIL_AUTO_UPDATE_PREVIEW = False
@ -486,6 +611,9 @@ Custom User Edit Forms
See :doc:`/advanced_topics/customisation/custom_user_models`.
``WAGTAIL_USER_EDIT_FORM``
--------------------------
.. code-block:: python
WAGTAIL_USER_EDIT_FORM = 'users.forms.CustomUserEditForm'
@ -493,6 +621,9 @@ See :doc:`/advanced_topics/customisation/custom_user_models`.
Allows the default ``UserEditForm`` class to be overridden with a custom form when
a custom user model is being used and extra fields are required in the user edit form.
``WAGTAIL_USER_CREATION_FORM``
------------------------------
.. code-block:: python
WAGTAIL_USER_CREATION_FORM = 'users.forms.CustomUserCreationForm'
@ -500,6 +631,9 @@ a custom user model is being used and extra fields are required in the user edit
Allows the default ``UserCreationForm`` class to be overridden with a custom form when
a custom user model is being used and extra fields are required in the user creation form.
``WAGTAIL_USER_CUSTOM_FIELDS``
------------------------------
.. code-block:: python
WAGTAIL_USER_CUSTOM_FIELDS = ['country']
@ -511,6 +645,9 @@ A list of the extra custom fields to be appended to the default list.
Usage for images, documents and snippets
========================================
``WAGTAIL_USAGE_COUNT_ENABLED``
--------------------------------
.. code-block:: python
WAGTAIL_USAGE_COUNT_ENABLED = True
@ -530,6 +667,9 @@ The link is also shown on the delete page, above the "Delete" button.
Date and DateTime inputs
========================
``WAGTAIL_DATE_FORMAT``, ``WAGTAIL_DATETIME_FORMAT``, ``WAGTAIL_TIME_FORMAT``
-----------------------------------------------------------------------------
.. code-block:: python
WAGTAIL_DATE_FORMAT = '%d.%m.%Y.'
@ -547,6 +687,9 @@ Time zones
Logged-in users can choose their current time zone for the admin interface in the account settings. If is no time zone selected by the user, then ``TIME_ZONE`` will be used.
(Note that time zones are only applied to datetime fields, not to plain time or date fields. This is a Django design decision.)
``WAGTAIL_USER_TIME_ZONES``
---------------------------
The list of time zones is by default the common_timezones list from pytz.
It is possible to override this list via the ``WAGTAIL_USER_TIME_ZONES`` setting.
If there is zero or one time zone permitted, the account settings form will be hidden.
@ -564,6 +707,9 @@ Users can choose between several languages for the admin interface
in the account settings. The list of languages is by default all the available
languages in Wagtail with at least 90% coverage. To change it, set ``WAGTAILADMIN_PERMITTED_LANGUAGES``:
``WAGTAILADMIN_PERMITTED_LANGUAGES``
------------------------------------
.. code-block:: python
WAGTAILADMIN_PERMITTED_LANGUAGES = [('en', 'English'),
@ -580,6 +726,9 @@ can only choose between front office languages:
Static files
============
``WAGTAILADMIN_STATIC_FILE_VERSION_STRINGS``
--------------------------------------------
.. code-block:: python
WAGTAILADMIN_STATIC_FILE_VERSION_STRINGS = False
@ -591,12 +740,17 @@ API Settings
For full documentation on API configuration, including these settings, see :ref:`api_v2_configuration` documentation.
``WAGTAILAPI_BASE_URL``
-----------------------
.. code-block:: python
WAGTAILAPI_BASE_URL = 'http://api.example.com/'
Required when using frontend cache invalidation, used to generate absolute URLs to document files and invalidating the cache.
``WAGTAILAPI_LIMIT_MAX``
------------------------
.. code-block:: python
@ -604,6 +758,8 @@ Required when using frontend cache invalidation, used to generate absolute URLs
Default is 20, used to change the maximum number of results a user can request at a time, set to ``None`` for no limit.
``WAGTAILAPI_SEARCH_ENABLED``
-----------------------------
.. code-block:: python
@ -611,6 +767,9 @@ Default is 20, used to change the maximum number of results a user can request a
Default is true, setting this to false will disable full text search on all endpoints.
``WAGTAILAPI_USE_FRONTENDCACHE``
--------------------------------
.. code-block:: python
WAGTAILAPI_USE_FRONTENDCACHE = True
@ -622,6 +781,8 @@ Frontend cache
For full documentation on frontend cache invalidation, including these settings, see :ref:`frontend_cache_purging`.
``WAGTAILFRONTENDCACHE``
------------------------
.. code-block:: python
@ -638,6 +799,8 @@ See documentation linked above for full options available.
``WAGTAILFRONTENDCACHE_LOCATION`` is no longer the preferred way to set the cache location, instead set the ``LOCATION`` within the ``WAGTAILFRONTENDCACHE`` item.
``WAGTAILFRONTENDCACHE_LANGUAGES``
----------------------------------
.. code-block:: python
@ -650,6 +813,9 @@ Default is an empty list, must be a list of languages to also purge the urls for
Rich text
=========
``WAGTAILADMIN_RICH_TEXT_EDITORS``
----------------------------------
.. code-block:: python
WAGTAILADMIN_RICH_TEXT_EDITORS = {
@ -678,12 +844,18 @@ If a ``'default'`` editor is not specified, rich text fields that do not specify
Page locking
============
``WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK``
--------------------------------------
``WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK`` can be set to ``True`` to prevent users
from editing pages that they have locked.
Redirects
=========
``WAGTAIL_REDIRECTS_FILE_STORAGE``
----------------------------------
.. code-block:: python
WAGTAIL_REDIRECTS_FILE_STORAGE = 'tmp_file'
@ -697,6 +869,9 @@ By default the redirect importer keeps track of the uploaded file as a temp file
Form builder
============
``WAGTAILFORMS_HELP_TEXT_ALLOW_HTML``
-------------------------------------
.. code-block:: python
WAGTAILFORMS_HELP_TEXT_ALLOW_HTML = True
@ -712,12 +887,18 @@ When true, HTML tags in form field help text will be rendered unescaped (default
Workflow
========
``WAGTAIL_WORKFLOW_ENABLED``
----------------------------
.. code-block:: python
WAGTAIL_WORKFLOW_ENABLED = False
Specifies whether moderation workflows are enabled (default: True). When disabled, editors will no longer be given the option to submit pages to a workflow, and the settings areas for admins to configure workflows and tasks will be unavailable.
``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT``
-----------------------------------------------
.. code-block:: python
WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = True
@ -728,6 +909,9 @@ This is the default, ``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = True`` . Th
tasks have already been approved, those tasks do not need to be reapproved. This is more suited to a hierarchical workflow system. To use workflows in this mode,
set ``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = False``.
``WAGTAIL_FINISH_WORKFLOW_ACTION``
----------------------------------
.. code-block:: python
WAGTAIL_FINISH_WORKFLOW_ACTION = 'wagtail.core.workflows.publish_workflow_state'
@ -735,6 +919,9 @@ set ``WAGTAIL_WORKFLOW_REQUIRE_REAPPROVAL_ON_EDIT = False``.
This sets the function to be called when a workflow completes successfully - by default, ``wagtail.core.workflows.publish_workflow_state``,
which publishes the page. The function must accept a ``WorkflowState`` object as its only positional argument.
``WAGTAIL_WORKFLOW_CANCEL_ON_PUBLISH``
--------------------------------------
.. code-block:: python
WAGTAIL_WORKFLOW_CANCEL_ON_PUBLISH = True