DOC Document how to include filenames for code blocks

.markdownlint-cli2.mjs

@@ -1,5 +1,4 @@
 
-// const extraRules = require("extraRules");
 import markdownlint from 'markdownlint';
 import enhancedProperNames from 'markdownlint-rule-enhanced-proper-names/src/enhanced-proper-names.js';
 import titleCaseStyle from 'markdownlint-rule-title-case-style';

en/00_Getting_Started/02_Composer.md

@@ -302,14 +302,6 @@ the ["Aliases" chapter of the Composer documentation](http://getcomposer.org/doc
 
 ## FAQ
 
-### Error "The requested package silverstripe/framework 1.0.0 could not be found"
-
-Composer needs hints about the base package version, either by using `composer create-project`
-as described above, or by checking out the `silverstripe-installer` project directly from version control. In order to
-use Composer on archive downloads from `silverstripe.org`, or other unversioned sources, an advanced workaround is to set
-the `COMPOSER_ROOT_VERSION` before every command
-([details](http://getcomposer.org/doc/03-cli.md#composer-root-version))
-
 ### How do I convert an existing module to using Composer?
 
 Simply decide on a [unique name and vendor prefix](https://packagist.org/about), create a `composer.json`, and either
@@ -324,7 +316,7 @@ on [packagist.org](http://packagist.org).
 
 Follow the packagist.org advice on choosing a [unique name and vendor prefix](https://packagist.org/about). Please don't
 use the `silverstripe/<modulename>` vendor prefix, since that's reserved for modules produced by Silverstripe Ltd. In
-order to declare that your module is in fact a Silverstripe CMS module, use the "Silverstripe" tag in the `composer.json`
+order to declare that your module is in fact a Silverstripe CMS module, use the `silverstripe` tag in the `composer.json`
 file, and set the "type" to "silverstripe-module".
 
 ### What about themes?

en/02_Developer_Guides/00_Model/02_Relations.md

@@ -560,7 +560,7 @@ class Tag extends DataObject
     /**
      * Example iterator placeholder for belongs_many_many.
      * This is a list of arbitrary types of objects
-     * @return \Generator|DataObject[]
+     * @return Generator|DataObject[]
      */
     public function getTaggedObjects()
     {

en/02_Developer_Guides/01_Templates/01_Syntax.md

@@ -6,7 +6,7 @@ icon: code
 
 # Template syntax
 
-A template can contain any markup language (e.g HTML, CSV, JSON..) and before being rendered to the user, they're
+A template can contain any markup language (e.g. HTML, CSV, JSON..) and before being rendered to the user, they're
 processed through [SSViewer](api:SilverStripe\View\SSViewer). This process replaces placeholders such as `$Var` with real content from your
 [model](../model) and allows you to define logic controls like `<% if $Var %>`.
 
@@ -454,7 +454,7 @@ For more information on formatting and casting variables see [Formatting, Modify
 ## Scope
 
 In the `<% loop %>` section, we saw an example of two **scopes**. Outside the `<% loop %>...<% end_loop %>`, we were in
-the scope of the top level `Page`. But inside the loop, we were in the scope of an item in the list (i.e the `Child`).
+the scope of the top level `Page`. But inside the loop, we were in the scope of an item in the list (i.e. the `Child`).
 
 The scope determines where the value comes from when you refer to a variable. Typically the outer scope of a `Page.ss`
 layout template is the [PageController](api:SilverStripe\CMS\Controllers\ContentController\PageController) that is currently being rendered.

en/02_Developer_Guides/01_Templates/02_Common_Variables.md

@@ -66,7 +66,7 @@ $Title
 $MenuTitle
 ```
 
-Most objects within Silverstripe CMS will respond to `$Title` (i.e they should have a `Title` database field or at least a
+Most objects within Silverstripe CMS will respond to `$Title` (i.e. they should have a `Title` database field or at least a
 `getTitle()` method).
 
 The CMS module in particular provides two fields to label a page: `Title` and `MenuTitle`. `Title` is the title

en/02_Developer_Guides/01_Templates/06_Themes.md

@@ -7,7 +7,7 @@ icon: paint-brush
 # Themes
 
 Themes can be used to kick start your Silverstripe CMS projects, can be stored outside of your application code and your
-application can provide multiple unique themes (i.e a mobile theme).
+application can provide multiple unique themes (i.e. a mobile theme).
 
 ## Downloading
 
@@ -27,7 +27,7 @@ composer require my_vendor/my_theme [version]
 
 [alert]
 As you've added new files to your Silverstripe CMS installation, make sure you clear the Silverstripe CMS cache by appending
-`?flush=1` to your website URL (e.g <http://yoursite.com/?flush=1>).
+`?flush=1` to your website URL (e.g. <http://yoursite.com/?flush=1>).
 [/alert]
 
 ### Configuring themes

en/02_Developer_Guides/01_Templates/index.md

@@ -10,7 +10,7 @@ icon: file-code
 Most of what will be public on your website comes from template files that are defined in Silverstripe CMS. Either in the
 core framework, the modules or themes you install, and your own custom templates.
 
-Silverstripe CMS templates are simple text files that have an `.ss` extension. They can contain any markup language (e.g HTML,
+Silverstripe CMS templates are simple text files that have an `.ss` extension. They can contain any markup language (e.g. HTML,
 XML, JSON..) and are processed to add features such as `$Var` to output variables and logic controls like
 `<% if $Var %>`. In this guide we'll look at the syntax of the custom template engine [SSViewer](api:SilverStripe\View\SSViewer) and how to render
 templates from your controllers.

en/02_Developer_Guides/02_Controllers/04_Redirection.md

@@ -21,7 +21,7 @@ class MyController extends Controller
 
     public function someMethod(): HTTPResponse
     {
-        // redirect to the "goherenow" action on this controller, i.e on the controller for the "contact-us" page this
+        // redirect to the "goherenow" action on this controller, i.e. on the controller for the "contact-us" page this
         // will redirect to /contact-us/goherenow/
         return $this->redirect($this->Link('goherenow'));
 

en/02_Developer_Guides/03_Forms/03_Form_Templates.md

@@ -29,11 +29,11 @@ modify as you need.
 [/notice]
 
 By default, Form and Fields follow the Silverstripe CMS template convention and are rendered into templates of the same
-class name (i.e `EmailField` will attempt to render into `EmailField.ss` and if that isn't found, `TextField.ss` or
+class name (i.e. `EmailField` will attempt to render into `EmailField.ss` and if that isn't found, `TextField.ss` or
 finally `FormField.ss`).
 
 [alert]
-While you can override all templates using normal view inheritance (i.e defining a `Form.ss`) other modules may rely on
+While you can override all templates using normal view inheritance (i.e. defining a `Form.ss`) other modules may rely on
 the core template structure. It is recommended to use `setTemplate()` and unique templates for specific forms.
 [/alert]
 
@@ -43,10 +43,10 @@ For [`FormField`](api:SilverStripe\Forms\FormField) instances, there are several
 $field = TextField::create();
 
 $field->setTemplate('CustomTextField');
-// Sets the template for the <input> tag. i.e '<input $AttributesHTML />'
+// Sets the template for the <input> tag. i.e. '<input $AttributesHTML />'
 
 $field->setFieldHolderTemplate('CustomTextField_Holder');
-// Sets the template for the wrapper around the text field. i.e
+// Sets the template for the wrapper around the text field. i.e.
 //    '<div class="text">'
 //
 // The actual FormField is rendered into the holder via the `$Field`

en/02_Developer_Guides/03_Forms/04_Form_Security.md

@@ -40,7 +40,7 @@ This token value is passed through the rendered Form HTML as a [HiddenField](api
 
 The token should be present whenever a operation has a side effect such as a `POST` operation.
 
-It can be safely disabled for `GET` requests as long as it does not modify the database (i.e a search form does not
+It can be safely disabled for `GET` requests as long as it does not modify the database (i.e. a search form does not
 normally require a security token).
 
 ```php
@@ -83,7 +83,7 @@ Forms can prepopulate submissions when a form is redisplayed with validation err
 and they by default contain CSRF tokens unique to the user's session.
 This data can inadvertently be stored either in a user's browser cache or in an intermediary
 cache such as a CDN or other caching-proxy. If incorrect `Cache-Control` headers are used, private data may be cached and
-accessible publicly through the CDN.  
+accessible publicly through the CDN.
 
 To ensure this doesn't happen Silverstripe CMS adds `Cache-Control: no-store, no-cache, must-revalidate` headers to any
 forms that have validators or security tokens (all of them by default) applied to them; this ensures that CDNs

en/02_Developer_Guides/03_Forms/05_Form_Transformations.md

@@ -19,7 +19,7 @@ $form = new Form(/* ... */);
 $form->makeReadonly();
 ```
 
-To make all the fields within a [FieldList](api:SilverStripe\Forms\FieldList) read-only (i.e to make fields read-only but not buttons).
+To make all the fields within a [FieldList](api:SilverStripe\Forms\FieldList) read-only (i.e. to make fields read-only but not buttons).
 
 ```php
 use SilverStripe\Forms\FieldList;

en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md

@@ -422,7 +422,7 @@ TinyMCEConfig::get('cms')
     ->addButtonsToLine(2, 'link', 'media');
 ```
 
-### Developing a wrapper to use a different WYSIWYG editors with hTMLEditorField
+### Developing a wrapper to use a different WYSIWYG editors with `HTMLEditorField`
 
 WYSIWYG editors are complex beasts, so replacing it completely is a difficult task.
 The framework provides a wrapper implementation for the basic required functionality,

en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md

@@ -9,7 +9,7 @@ You can add an action to the row(s) of a [GridField](/developer_guides/forms/fie
 In a [GridField](/developer_guides/forms/field_types/gridfield) instance each table row can have a
 number of actions located the end of the row.
 Each action is represented as a instance of a specific class
-(e.g [GridFieldEditButton](api:SilverStripe\Forms\GridField\GridFieldEditButton)) which has been added to the `GridFieldConfig`
+(e.g. [GridFieldEditButton](api:SilverStripe\Forms\GridField\GridFieldEditButton)) which has been added to the `GridFieldConfig`
 for that `GridField`
 
 As a developer, you can create your own custom actions to be located alongside
@@ -159,12 +159,12 @@ this interface we have to define two methods to describe the behavior of the
 action:
 
 - `getActions` returns an array of all the custom actions we want this class to
- handle (i.e `docustomaction`) .
+ handle (i.e. `docustomaction`) .
 - `handleAction` method which will contain the logic for performing the
- specific action (e.g publishing the row to a thirdparty service).
+ specific action (e.g. publishing the row to a thirdparty service).
 
 Inside `handleAction` we have access to the current GridField and GridField row
-through the `$arguments`. If your column provides more than one action (e.g two
+through the `$arguments`. If your column provides more than one action (e.g. two
 links) both actions will be handled through the one `handleAction` method. The
 called method is available as a parameter.
 

en/02_Developer_Guides/04_Configuration/01_SiteConfig.md

@@ -34,7 +34,7 @@ echo $config->Title;
 // returns "Website Name"
 ```
 
-## Extending siteConfig
+## Extending `SiteConfig`
 
 To extend the options available in the panel, define your own fields via a [DataExtension](api:SilverStripe\ORM\DataExtension).
 
@@ -73,7 +73,7 @@ Silverstripe\SiteConfig\SiteConfig:
 
 [notice]
 After adding the class and the YAML change, make sure to rebuild your database by visiting <http://example.com/dev/build>.
-You may also need to reload the screen with a `?flush=1` i.e <http://example.com/admin/settings?flush=1>.
+You may also need to reload the screen with a `?flush=1` i.e. <http://example.com/admin/settings?flush=1>.
 [/notice]
 
 You can define as many extensions for `SiteConfig` as you need. For example, if you're developing a module and want to

en/02_Developer_Guides/05_Extending/00_Modules.md

@@ -74,7 +74,7 @@ Then clone the Module Skeleton to get a headstart with the module files:
 
 ```bash
 cd /vendor/my_vendor/nice_feature
-git clone [email protected]:silverstripe/silverstripe-module.git .
+git clone [email protected]:silverstripe/silverstripe-module.g.it .
 ```
 
 ### Allow your module to be importable by composer
@@ -105,7 +105,7 @@ Push your module upstream to the empty repository just created:
  git init
  git add -A
  git commit -m 'first commit'
- git remote add origin [email protected]:my_vendor/nice_feature.git
+ git remote add origin [email protected]:my_vendor/nice_feature.g.it
  git push -u origin master
 ```
 
@@ -124,7 +124,7 @@ For our *nice_module* example module we have just pushed upstream and can add th
 "repositories": [
     {
         "type": "vcs",
-        "url": "[email protected]:my_vendor/nice_feature.git",
+        "url": "[email protected]:my_vendor/nice_feature.g.it",
     }
 ]
 ```

en/02_Developer_Guides/05_Extending/01_Extensions.md

@@ -4,7 +4,7 @@ summary: Extensions and DataExtensions let you modify and augment objects transp
 icon: code
 ---
 
-# Extensions and dataExtensions
+# `Extension` and `DataExtension`
 
 An [Extension](api:SilverStripe\Core\Extension) allows for adding additional functionality to a class or modifying existing functionality
 without the hassle of creating a subclass. Developers can add Extensions to any PHP class that has the [Extensible](api:SilverStripe\Core\Extensible)

en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md

@@ -97,7 +97,7 @@ As a convention, the `master` branch of your module should always work with the
 
 Other branches should be created on your module as needed if they're required to support specific Silverstripe CMS releases.
 
-You can have an overlap in supported versions, e.g two branches in your module both support Silverstripe CMS 3.1. In this
+You can have an overlap in supported versions, e.g. two branches in your module both support Silverstripe CMS 3.1. In this
 case, you should explain the differences in your `README.md` file.
 
 Here's some common values for your `require` section

en/02_Developer_Guides/06_Testing/00_Unit_Testing.md

@@ -43,7 +43,7 @@ class PageTest extends SapphireTest
 Tests for your application should be stored in the `app/tests` directory. Test cases for add-ons should be stored in
 the `(modulename)/tests` directory.
 
-Test case classes should end with `Test` (e.g `PageTest`) and test methods must start with `test` (e.g `testMyMethod`).
+Test case classes should end with `Test` (e.g. `PageTest`) and test methods must start with `test` (e.g. `testMyMethod`).
 
 Ensure you [import](http://php.net/manual/en/language.namespaces.importing.php#example-252) any classes you need for the test, including `SilverStripe\Dev\SapphireTest` or `SilverStripe\Dev\FunctionalTest`.
 [/info]

en/02_Developer_Guides/06_Testing/01_Functional_Testing.md

@@ -15,7 +15,7 @@ creating [HTTPRequest](api:SilverStripe\Control\HTTPRequest), receiving [HTTPRes
 $page = $this->get($url);
 ```
 
-Performs a GET request on $URL and retrieves the [HTTPResponse](api:SilverStripe\Control\HTTPResponse). This also changes the current page to the value
+Performs a GET request on `$url` and retrieves the [HTTPResponse](api:SilverStripe\Control\HTTPResponse). This also changes the current page to the value
 of the response.
 
 ## Post
@@ -24,7 +24,7 @@ of the response.
 $page = $this->post($url);
 ```
 
-Performs a POST request on $URL and retrieves the [HTTPResponse](api:SilverStripe\Control\HTTPResponse). This also changes the current page to the value
+Performs a POST request on `$url` and retrieves the [HTTPResponse](api:SilverStripe\Control\HTTPResponse). This also changes the current page to the value
 of the response.
 
 [notice]
@@ -38,7 +38,7 @@ Silverstripe CMS 4.6 and later always sends a POST request for consistency.
 $page = $this->sendRequest('PUT', $url);
 ```
 
-Performs a request on $URL with the HTTP method provided (useful for PUT, PATCH, DELETE, etc.). This also changes the current page to the value of the response.
+Performs a request on `$url` with the HTTP method provided (useful for PUT, PATCH, DELETE, etc.). This also changes the current page to the value of the response.
 
 ## Submit
 
@@ -70,7 +70,7 @@ $this->logOut();
 
 The `FunctionalTest` class also provides additional asserts to validate your tests.
 
-### AssertPartialMatchBySelector
+### `assertPartialMatchBySelector`
 
 ```php
 $this->assertPartialMatchBySelector('p.good', [
@@ -82,7 +82,7 @@ Asserts that the most recently queried page contains a number of content tags sp
 selector will be applied to the HTML of the most recent page. The content of every matching tag will be examined. The
 assertion fails if one of the expectedMatches fails to appear.
 
-### AssertExactMatchBySelector
+### `assertExactMatchBySelector`
 
 ```php
 $this->assertExactMatchBySelector('#MyForm_ID p.error', [
@@ -94,7 +94,7 @@ Asserts that the most recently queried page contains a number of content tags sp
 selector will be applied to the HTML of the most recent page. The full HTML of every matching tag will be examined. The
 assertion fails if one of the expectedMatches fails to appear.
 
-### AssertPartialHTMLMatchBySelector
+### `assertPartialHTMLMatchBySelector`
 
 ```php
 $this->assertPartialHTMLMatchBySelector('#MyForm_ID p.error', [
@@ -110,7 +110,7 @@ assertion fails if one of the expectedMatches fails to appear.
 ` ` characters are stripped from the content; make sure that your assertions take this into account.
 [/notice]
 
-### AssertExactHTMLMatchBySelector
+### `assertExactHTMLMatchBySelector`
 
 ```php
 $this->assertExactHTMLMatchBySelector('#MyForm_ID p.error', [

en/02_Developer_Guides/06_Testing/04_Fixtures.md

@@ -153,7 +153,7 @@ database field (TeamID).
 Also be aware the target of a relationship must be defined before it is referenced, for example the `hurricanes` team must appear in the fixture file before the line `Team: =>App\Test\Team.hurricanes`.
 [/hint]
 
-This style of relationship declaration can be used for any type of relationship (i.e `has_one`, `has_many`, `many_many`).
+This style of relationship declaration can be used for any type of relationship (i.e. `has_one`, `has_many`, `many_many`).
 
 We can also declare the relationships conversely. Another way we could write the previous example is:
 

en/02_Developer_Guides/07_Debugging/01_Error_Handling.md

@@ -312,7 +312,7 @@ it:
 - Create a `SilverStripe\Logging\MonologErrorHandler` object.
 - Attach the registered service `Psr\Log\LoggerInterface` to it, to start the error handler.
 
-Core.PHP will call `start()` on this method, to start the error handler.
+`Core.php` will call `start()` on this method, to start the error handler.
 
 This error handler is flexible enough to work with any PSR-3 logging implementation, but sometimes you will want to use
 another. To replace this, you should registered a new service, `ErrorHandlerLoader`.  For example:

en/02_Developer_Guides/08_Performance/04_Static_Publishing.md

@@ -17,4 +17,4 @@ If you want to cache part of a page, or your site has interactive elements such
 By publishing the page as HTML it's possible to run Silverstripe CMS from behind a corporate firewall, on a low performance
 server or serve millions of hits an hour without expensive hardware.
 
-This functionality is available through the [Static Publisher with Queue](https://github.com/silverstripe/silverstripe-staticpublishqueue) module. The module provides hooks for developers to generate static HTML files for the whole application or publish key pages (e.g a web applications home page) as HTML to reduce load on the server.
+This functionality is available through the [Static Publisher with Queue](https://github.com/silverstripe/silverstripe-staticpublishqueue) module. The module provides hooks for developers to generate static HTML files for the whole application or publish key pages (e.g. a web applications home page) as HTML to reduce load on the server.

en/02_Developer_Guides/09_Security/01_Access_Control.md

@@ -53,7 +53,7 @@ works.
 
 ### Loading the admin page: looking at security
 
-If you go to [your site]/admin *Director.PHP* maps the 'admin' URL request through a [Director](api:SilverStripe\Control\Director) rule to the
+If you go to [your site]/admin `Director.php` maps the 'admin' URL request through a [Director](api:SilverStripe\Control\Director) rule to the
 [CMSMain](api:SilverStripe\CMS\Controllers\CMSMain) controller (see [CMSMain](api:SilverStripe\CMS\Controllers\CMSMain), with no arguments).
 
 *CMSMain.init()* calls its parent which, of all things is called [LeftAndMain](api:SilverStripe\Admin\LeftAndMain). It's in [LeftAndMain](api:SilverStripe\Admin\LeftAndMain) that the

en/02_Developer_Guides/11_Integration/00_CSV_Import.md

@@ -12,7 +12,7 @@ but this method doesn't know anything about your datamodel. In Silverstripe CMS,
 this can be handled through the a specialized CSV importer class that can
 be customised to fit your data.
 
-## The csvBulkLoader class
+## The `CsvBulkLoader` class
 
 The [CsvBulkLoader](api:SilverStripe\Dev\CsvBulkLoader) class facilitate complex CSV-imports by defining column-mappings and custom converters.
 It uses PHP's built-in `fgetcsv()` function to process CSV input, and accepts a file handle as an input.