fix up legacy release note refs & use consistent format

- fix some broken refs that were lost in the migration to markdown files
- use lower_snake_case for all internal refs (most follow this convention)
- release process sub-section in docs should be named release schedule instead

docs/advanced_topics/embeds.md

@@ -8,7 +8,7 @@ code directly from the relevant provider's site using the oEmbed protocol.
 
 Wagtail has a built-in list of the most common providers and this list can be
 changed [with a setting](customising_embed_providers). Wagtail also supports
-fetching embed code using [Embedly](Embedly) and [custom embed finders](custom_embed_finders).
+fetching embed code using [Embedly](embedly) and [custom embed finders](custom_embed_finders).
 
 ## Embedding content on your site
 
@@ -234,7 +234,7 @@ By passing `'omitscript': True` in the configuration, you can indicate that thes
 tags should be omitted from the embed HTML. Note that you will then have to take care of
 loading this script yourself.
 
-(Embedly)=
+(embedly)=
 
 ### Embed.ly
 

docs/advanced_topics/i18n.md

@@ -687,7 +687,7 @@ If your language isn't listed on that page, you can easily contribute new langua
 
 Logged-in users can set their preferred language from `/admin/account/`.
 By default, Wagtail provides a list of languages that have a >= 90% translation coverage.
-It is possible to override this list via the [WAGTAILADMIN_PERMITTED_LANGUAGES](WAGTAILADMIN_PERMITTED_LANGUAGES) setting.
+It is possible to override this list via the [WAGTAILADMIN_PERMITTED_LANGUAGES](wagtailadmin_permitted_languages) setting.
 
 In case there is zero or one language permitted, the form will be hidden.
 

docs/contributing/documentation_guidelines.md

@@ -108,7 +108,7 @@ A [link to a reference](register_reports_menu_item).
 
 #### Reference links
 
-Reference links (links to a target within a page) rely on the page having a reference created, this can be added as follows:
+Reference links (links to a target within a page) rely on the page having a reference created. Each reference must have a unique name and should use the `lower_snake_case` format. A reference can be added as follows:
 
 ```md
 (my_awesome_section)=

docs/contributing/documentation_modes.md

@@ -10,7 +10,7 @@ Each type of information delivery has a purpose and targets a specific audience.
 
 We are following Daniele Procida's [Diátaxis documentation framework](https://diataxis.fr/).
 
-(choose-a-writing-mode)=
+(choose_a_writing_mode)=
 
 ## Choose a writing mode
 

docs/contributing/release_process.md

@@ -28,7 +28,7 @@ issued from those branches.
 **Feature release**
 
 Feature releases (A.B, A.B+1, etc.) happen every three months
--- see [release process](release-process) for details. These releases will contain new
+-- see [release schedule](release_schedule) for details. These releases will contain new
 features and improvements to existing features.
 
 **Patch release**
@@ -145,9 +145,9 @@ and after the following releases:
 Wagtail 1.5 will support Django 1.8 (LTS), 1.9, 1.10.
 Wagtail 1.4 will still support only Django 1.8 (LTS) and 1.9.
 
-(release-process)=
+(release_schedule)=
 
-## Release process
+## Release schedule
 
 Wagtail uses a [time-based release schedule](https://github.com/wagtail/wagtail/wiki/Release-schedule),
 with feature releases every three months.

docs/editor_manual/finding_your_way_around/the_dashboard.md

@@ -4,7 +4,7 @@ The Dashboard provides information on:
 
 -   The number of pages, images, and documents currently held in the Wagtail CMS
 -   Any pages currently awaiting moderation (if you have these privileges)
--   Any pages that you've locked (if your administrator has enabled {ref}`author-specific locking<WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK>`)
+-   Any pages that you've locked (if your administrator has enabled {ref}`author-specific locking<wagtailadmin_global_page_edit_lock>`)
 -   Your most recently edited pages
 
 You can return to the Dashboard at any time by clicking the Wagtail logo in the top-left of the screen.

docs/extending/rich_text_internals.md

@@ -199,7 +199,7 @@ def register_embed_handler(features):
 
 ## Editor widgets
 
-The editor interface used on rich text fields can be configured with the [WAGTAILADMIN_RICH_TEXT_EDITORS](WAGTAILADMIN_RICH_TEXT_EDITORS) setting. Wagtail provides an implementation: `wagtail.admin.rich_text.DraftailRichTextArea` (the [Draftail](https://www.draftail.org/) editor based on [Draft.js](https://draftjs.org/)).
+The editor interface used on rich text fields can be configured with the [WAGTAILADMIN_RICH_TEXT_EDITORS](wagtailadmin_rich_text_editors) setting. Wagtail provides an implementation: `wagtail.admin.rich_text.DraftailRichTextArea` (the [Draftail](https://www.draftail.org/) editor based on [Draft.js](https://draftjs.org/)).
 
 It is possible to create your own rich text editor implementation. At minimum, a rich text editor is a Django **_class_ django.forms.Widget** subclass whose constructor accepts an `options` keyword argument (a dictionary of editor-specific configuration options sourced from the `OPTIONS` field in `WAGTAILADMIN_RICH_TEXT_EDITORS`), and which consumes and produces string data in the HTML-like format described above.
 

docs/getting_started/tutorial.md

@@ -186,7 +186,7 @@ Edit `home/templates/home/home_page.html` to contain the following:
 ### Wagtail template tags
 
 In addition to Django's [template tags and filters](https://docs.djangoproject.com/en/3.1/ref/templates/builtins/),
-Wagtail provides a number of its own [template tags & filters](template-tags-and-filters)
+Wagtail provides a number of its own [template tags & filters](template_tags_and_filters)
 which can be loaded by including `{% load wagtailcore_tags %}` at the top of
 your template file.
 

docs/reference/contrib/settings.md

@@ -47,6 +47,8 @@ class SiteSpecificSocialMediaSettings(BaseSiteSetting):
 
 Links to your settings will appear in the Wagtail admin 'Settings' menu.
 
+(edit_handlers_settings)=
+
 ## Edit handlers
 
 Settings use edit handlers much like the rest of Wagtail.

docs/reference/settings.md

@@ -174,7 +174,7 @@ This setting lets you change the number of items shown at 'Your most recent edit
 
 ## General editing
 
-(WAGTAILADMIN_RICH_TEXT_EDITORS)=
+(wagtailadmin_rich_text_editors)=
 
 ### `WAGTAILADMIN_RICH_TEXT_EDITORS`
 
@@ -199,7 +199,7 @@ Customise the behaviour of rich text fields. By default, `RichTextField` and `Ri
 
 If a `'default'` editor is not specified, rich text fields that do not specify an `editor` argument will use the Draftail editor with the default feature set enabled.
 
-(WAGTAILADMIN_EXTERNAL_LINK_CONVERSION)=
+(wagtailadmin_external_link_conversion)=
 
 ### `WAGTAILADMIN_EXTERNAL_LINK_CONVERSION`
 
@@ -238,6 +238,8 @@ WAGTAIL_ALLOW_UNICODE_SLUGS = True
 
 By default, page slugs can contain any alphanumeric characters, including non-Latin alphabets. Set this to False to limit slugs to ASCII characters.
 
+(wagtail_auto_update_preview)=
+
 ### `WAGTAIL_AUTO_UPDATE_PREVIEW`
 
 ```python
@@ -255,7 +257,7 @@ WAGTAIL_AUTO_UPDATE_PREVIEW_INTERVAL = 500
 
 The interval (in milliseconds) to check for changes made in the page editor before updating the preview. The default value is `500`.
 
-(WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK)=
+(wagtailadmin_global_page_edit_lock)=
 
 ### `WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK`
 
@@ -328,7 +330,7 @@ Specifies the number of images per page shown on the main Images listing in the
 WAGTAILIMAGES_USAGE_PAGE_SIZE = 20
 ```
 
-Specifies the number of items per page shown when viewing an image's usage (see [`WAGTAIL_USAGE_COUNT_ENABLED`](WAGTAIL_USAGE_COUNT_ENABLED)).
+Specifies the number of items per page shown when viewing an image's usage (see [`WAGTAIL_USAGE_COUNT_ENABLED`](wagtail_usage_count_enabled)).
 
 ### `WAGTAILIMAGES_CHOOSER_PAGE_SIZE`
 
@@ -525,7 +527,7 @@ WAGTAIL_GRAVATAR_PROVIDER_URL = '//www.gravatar.com/avatar'
 
 If a user has not uploaded a profile picture, Wagtail will look for an avatar linked to their email address on gravatar.com. This setting allows you to specify an alternative provider such as like robohash.org, or can be set to `None` to disable the use of remote avatars completely.
 
-(WAGTAIL_USER_TIME_ZONES)=
+(wagtail_user_time_zones)=
 
 ### `WAGTAIL_USER_TIME_ZONES`
 
@@ -540,7 +542,7 @@ If there is zero or one time zone permitted, the account settings form will be h
 WAGTAIL_USER_TIME_ZONES = ['America/Chicago', 'Australia/Sydney', 'Europe/Rome']
 ```
 
-(WAGTAILADMIN_PERMITTED_LANGUAGES)=
+(wagtailadmin_permitted_languages)=
 
 ### `WAGTAILADMIN_PERMITTED_LANGUAGES`
 
@@ -659,7 +661,7 @@ TAG_LIMIT = 5
 
 Limit the number of tags that can be added to (django-taggit) Tag model. Default setting is `None`, meaning no limit on tags.
 
-(WAGTAIL_USAGE_COUNT_ENABLED)=
+(wagtail_usage_count_enabled)=
 
 ## Usage for images, documents and snippets
 

docs/reference/streamfield/blocks.md

@@ -202,7 +202,7 @@ All block definitions accept the following optional keyword arguments:
 
    A WYSIWYG editor for creating formatted text including links, bold / italics etc. The following keyword arguments are accepted in addition to the standard ones:
 
-   :param editor: The rich text editor to be used (see :ref:`WAGTAILADMIN_RICH_TEXT_EDITORS`).
+   :param editor: The rich text editor to be used (see :ref:`wagtailadmin_rich_text_editors`).
    :param features: Specifies the set of features allowed (see :ref:`rich_text_features`).
    :param required: If true (the default), the field cannot be left blank.
    :param max_length: The maximum allowed length of the field. Only text is counted; rich text formatting, embedded content and paragraph / line breaks do not count towards the limit.

docs/releases/1.10.rst

@@ -33,7 +33,7 @@ Wagtail is now compatible with Django 1.11 and Python 3.6. Compatibility fixes w
 User language preference
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Users can now set their preferred language for the Wagtail admin interface under Account Settings → Language Preferences. The list of available languages can be configured via the :ref:`WAGTAILADMIN_PERMITTED_LANGUAGES <WAGTAILADMIN_PERMITTED_LANGUAGES>` setting. This feature was developed by Daniel Chimeno.
+Users can now set their preferred language for the Wagtail admin interface under Account Settings → Language Preferences. The list of available languages can be configured via the :ref:`WAGTAILADMIN_PERMITTED_LANGUAGES <wagtailadmin_permitted_languages>` setting. This feature was developed by Daniel Chimeno.
 
 
 New admin preview
@@ -43,7 +43,7 @@ Previewing pages in Wagtail admin interface was rewritten
 to make it more robust. In previous versions, preview was broken in several
 scenarios so users often ended up on a blank page with an infinite spinner.
 
-An additional setting was created: :ref:`WAGTAIL_AUTO_UPDATE_PREVIEW <WAGTAIL_AUTO_UPDATE_PREVIEW>`.
+An additional setting was created: :ref:`WAGTAIL_AUTO_UPDATE_PREVIEW <wagtail_auto_update_preview>`.
 It allows users to see changes done in the editor by refreshing the preview tab
 without having to click again on the preview button.
 

docs/releases/1.5.rst

@@ -65,7 +65,7 @@ Minor features
 ~~~~~~~~~~~~~~
 
 * Password reset email now reminds the user of their username (Matt Westcott)
-* Added :ref:`jinja2 support <settings_tag_jinja2>` for the  ``settings`` template tag (Tim Heap)
+* Added jinja2 support for the  ``settings`` template tag (Tim Heap)
 * Added 'revisions' action to pages list (Roel Bruggink)
 * Added a hook :ref:`insert_global_admin_js` for inserting custom JavaScript throughout the admin backend (Tom Dyson)
 * Recognise instagram embed URLs with ``www`` prefix (Matt Westcott)

docs/releases/2.1.rst

@@ -34,7 +34,7 @@ The API now includes an endpoint for finding pages by path; see :ref:`apiv2_find
 User time zone setting
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Users can now set their current time zone through the Account Settings menu, which will then be reflected in date / time fields throughout the admin (such as go-live / expiry dates). The list of available time zones can be configured via the :ref:`WAGTAIL_USER_TIME_ZONES <WAGTAIL_USER_TIME_ZONES>` setting. This feature was developed by David Moore.
+Users can now set their current time zone through the Account Settings menu, which will then be reflected in date / time fields throughout the admin (such as go-live / expiry dates). The list of available time zones can be configured via the :ref:`WAGTAIL_USER_TIME_ZONES <wagtail_user_time_zones>` setting. This feature was developed by David Moore.
 
 
 Elasticsearch 6 support

docs/releases/2.15.rst

@@ -77,7 +77,7 @@ Particular thanks to LB, who reviewed almost all of those contributions, and Kyl
 Other features
 ~~~~~~~~~~~~~~
 
- * Add the ability for the page chooser to convert external urls that match a page to internal links, see :ref:`WAGTAILADMIN_EXTERNAL_LINK_CONVERSION` (Jacob Topp-Mugglestone. Sponsored by The Motley Fool)
+ * Add the ability for the page chooser to convert external urls that match a page to internal links, see :ref:`wagtailadmin_external_link_conversion` (Jacob Topp-Mugglestone. Sponsored by The Motley Fool)
  * Added "Extending Wagtail" section to documentation (Matt Westcott)
  * Introduced :doc:`template components </extending/template_components>`, a standard mechanism for renderable objects in the admin (Matt Westcott)
  * Support ``min_num`` / ``max_num`` options on ListBlock (Matt Westcott)

docs/topics/writing_templates.md

@@ -68,7 +68,7 @@ Images from the library must be requested using this syntax, but a developer's s
 
 Read more about the image manipulation syntax here: [](image_tag).
 
-(template-tags-and-filters)=
+(template_tags_and_filters)=
 
 ## Template tags & filters