Fix docs format (#14751)

OrchardCMS · Dec 3, 2023 · 2e15d6e · 2e15d6e
1 parent dbdc447
commit 2e15d6e
Show file tree

Hide file tree

Showing 115 changed files with 847 additions and 817 deletions.
diff --git a/src/docs/getting-started/README.md b/src/docs/getting-started/README.md
@@ -12,6 +12,7 @@ In Visual Studio, create a new empty .NET Core web application. Ex: `Cms.Web`. D
 To add a reference to the package, right-click on the project and click on `Manage NuGet packages...`, check `Include prerelease` if required. If you added the preview source above, select this from the `Package Source` selection in the top right.  In the `Browse` tab, search for `OrchardCore.Application.Cms.Targets` and `Install` the package.
 
 ### Getting Started with `Program.cs` Only Using .NET 6 Framework?
+
 !!! tip
     When starting a new project using `.NET 6` framework, you'll notice that the created project does not have a `Startup` class as it did in previous versions of the .NET framework.
 
@@ -21,7 +22,7 @@ Open `Program.cs` file. Remove the following line "if exists"
 builder.Services.AddRazorPages();
 ```
 
-Add the following line 
+Add the following line
 
 ```csharp
 builder.Services.AddOrchardCms();
@@ -35,6 +36,7 @@ app.UseRouting();
 app.UseAuthorization();
 app.MapRazorPages();
 ```
+
 Lastly, add the following line to the request pipeline
 
 ```csharp

diff --git a/src/docs/getting-started/preview-package-source.md b/src/docs/getting-started/preview-package-source.md
@@ -14,7 +14,6 @@ The feed url is <https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json>
 
 ![image](assets/add-preview-package-source.png)
 
-
 ## Adding Orchard Core preview Feed with NuGet.config
 
 You can also add the package source by using a NuGet.config file:

diff --git a/src/docs/getting-started/starter-recipes.md b/src/docs/getting-started/starter-recipes.md
@@ -5,7 +5,7 @@ Orchard Core is available for use via two different NuGet meta packages.
 - `OrchardCore.Application.Cms.Core.Targets`
 - `OrchardCore.Application.Cms.Targets`
 
-The first package `OrchardCore.Application.Cms.Core.Targets` is intended for use when 
+The first package `OrchardCore.Application.Cms.Core.Targets` is intended for use when
 
 - Developing a Decoupled Web Site
 - Developing a Headless Web Site
@@ -26,7 +26,7 @@ The second package `OrchardCore.Application.Cms.Targets` contains all of the abo
 Recipes in Orchard Core help you get your site setup by enabling features,
 and / or creating content types, and content for your site.
 
-Orchard Core Themes can contain Razor or Liquid views, and by default use 
+Orchard Core Themes can contain Razor or Liquid views, and by default use
 Orchard Core Display Management techniques to render content.
 
 ## OrchardCore.Application.Cms.Core.Targets
@@ -40,7 +40,7 @@ or when building your own theme.
 Alternatively you can start with another recipe,
 and change the active theme after setup.
 
-#### Blank Recipe Contents 
+#### Blank Recipe Contents
 
 - Content management features
 - Activates `TheAdmin` theme
@@ -84,7 +84,7 @@ TheBlogTheme is based on the [Start Bootstrap Clean Blog Theme](https://startboo
 
 ### Blog - Lucene Query Recipe
 
-The Lucene Query recipe is an optional recipe in the TheBlogTheme. 
+The Lucene Query recipe is an optional recipe in the TheBlogTheme.
 This recipe runs the Blog Lucene Search recipe and as an example,
 the recipe replaces the RecentBlogPosts SQL query with a Lucene query.
 
@@ -95,13 +95,13 @@ the recipe replaces the RecentBlogPosts SQL query with a Lucene query.
 
 ### Blog - Lucene Search Recipe
 
-The Lucene Search recipe is an optional recipe in the TheBlogTheme. 
+The Lucene Search recipe is an optional recipe in the TheBlogTheme.
 This recipe enables the Lucene feature and creates Search setting, Lucene indices and permissions.
 
 #### Blog Lucene Search Recipe Contents
 
 - Enables Lucene feature
-- Setup Lucene indices 
+- Setup Lucene indices
 - Create the search settings
 - Search index permission
 
@@ -139,7 +139,7 @@ TheComingSoon theme is based on the [Start Bootstrap Coming Soon Theme](https://
 
 The Saas recipe includes a Software as a Service multi tenancy configuration.
 
-It configures the site to use TheTheme, and you are then able to create Tenants 
+It configures the site to use TheTheme, and you are then able to create Tenants
 using any of the other recipes.
 
 #### Saas Recipe Contents

diff --git a/src/docs/getting-started/theme.md b/src/docs/getting-started/theme.md
@@ -4,7 +4,7 @@ In this article, we are going to create an Orchard Core Theme by adding it to an
 
 ## Create an Orchard Core Theme
 
-- Install the [Code Generation Templates](templates/README.md) 
+- Install the [Code Generation Templates](templates/README.md)
 - Create a folder alongside (*not* within) the application folder created before, with the name of your theme (Ex: `MyTheme.OrchardCore`). Preferably create a new folder under `OrchardCore.Themes` directory. Open it. We are going to create a new project in this folder.
 - Execute the command `dotnet new octheme`
 - In Visual Studio, add the newly created theme project to the solution, then add a reference to the project from the main Orchard Core CMS Web application.
@@ -33,13 +33,10 @@ The theme should be available in the `Active themes` admin page, and can be set
 
 ## How to enable Razor templates in my theme?
 
-The themes we have in source code uses only `Liquid` files so their .csproj only reference : 
+The themes we have in source code uses only `Liquid` files so their .csproj only reference :
 
 `<Project Sdk="Microsoft.NET.Sdk">`
 
 If you want to use Razor templates in your theme you simply need to change this .csproj first line for :
 
 `<Project Sdk="Microsoft.NET.Sdk.Razor">`
-
-
-
diff --git a/src/docs/guides/add-admin-menu/README.md b/src/docs/guides/add-admin-menu/README.md
@@ -43,7 +43,7 @@ We also need a reference to the `OrchardCore.Admin` package in order to be able
 ```dotnet add .\MyModule\MyModule.csproj package OrchardCore.Admin --version 1.7.2-*```
 
 !!! note
-    To use the development branch of the template add ` --source https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json --version 1.7.2-*`
+    To use the development branch of the template add `--source https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json --version 1.7.2-*`
 
 ## Adding our controller and views
 

diff --git a/src/docs/guides/content-definitions/README.md b/src/docs/guides/content-definitions/README.md
@@ -4,7 +4,7 @@
 
 By default the `Content Definitions` are stored in the database.
 
-When the `File Content Definition` feature is enabled it stores content definitions in a `ContentDefinition.json` file 
+When the `File Content Definition` feature is enabled it stores content definitions in a `ContentDefinition.json` file
 at the root of each tenants `App_Data` folder, e.g. `App_Data/Sites/Default/ContentDefinition.json` for the default tenant.
 
 The `File Content Definition` feature can be very useful during the `Development` phase of a project.
@@ -39,4 +39,3 @@ This will download a file called `ContentDefinitions.zip` to your computer.
 ## Summary
 
 You just learnt how to create a `Deployment Plan` to migrate from the `File Content Definition` feature.
-
diff --git a/src/docs/guides/create-admin-theme/README.md b/src/docs/guides/create-admin-theme/README.md
@@ -4,12 +4,10 @@ A custom Admin Theme may be created for Orchard Core.
 
 The default admin theme for Orchard Core is called `TheAdmin`
 
-
 ## What you will build
 
 You will build a custom theme which uses `TheAdmin` as a base theme.
 
-
 ## What you will need
 
 - An existing Orchard Core website that has already been setup.
@@ -47,7 +45,7 @@ will search both `TheAdmin` theme and `MyAdminTheme` for template alternates whe
 
 Views in `MyAdminTheme` will override views in `TheAdmin`.
 
-## Enabling your custom admin theme.
+## Enabling your custom admin theme
 
 From the root of the folder containing both projects, run this command:
 

diff --git a/src/docs/guides/create-liquid-widget/README.md b/src/docs/guides/create-liquid-widget/README.md
@@ -49,7 +49,7 @@ The standard template contains wrapper divs and you may wish to customize how th
 </div>
 ```
 
-To customize this template 
+To customize this template
 
 - Navigate to _Design -> Templates_
 

diff --git a/src/docs/guides/decoupled-cms/README.md b/src/docs/guides/decoupled-cms/README.md
@@ -72,6 +72,7 @@ This will allow for the Razor Pages to be reloaded without the need to recompile
   <PackageReference Include="OrchardCore.Application.Cms.Core.Targets" Version="1.7.2" />
 </ItemGroup>
 ```
+
 This will add the packages from Orchard Core CMS
 
 - Edit the `Program.cs` file to configure OrchardCore CMS services like this:
@@ -84,7 +85,7 @@ builder.Services.AddOrchardCms();
     `builder.Services.AddRazorPages()` must not be called directly as `builder.Services.AddOrchardCms()` already invokes it internally.
 
 - Edit the `Program.cs` file
-- Add `app.UseOrchardCore();` 
+- Add `app.UseOrchardCore();`
 - If any of the following lines exists in your `Program.cs` file, remove them:
 
 ```csharp
@@ -353,7 +354,6 @@ The changes consist in using the `slug` name in both the route and the local pro
 
 ### Generating the slug using a custom pattern
 
-
 The __Alias Part__ provides some custom settings in order to let it be generated automatically. In our case we want it to be generated from the __Title__, automatically. To provide such patterns the CMS uses a templating language named __Liquid__, together with some custom functions to manipulate content items' properties. Orchard provides a generally suitable default pattern.
 
 - Edit the content definition of Blog Post, and for the __Alias Part__ click on __Edit__.
@@ -417,4 +417,4 @@ In this tutorial we have learned how to
 
 ## Video
 
-<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/yWpz8p-oaKg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/yWpz8p-oaKg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
diff --git a/src/docs/guides/encoding-settings/README.md b/src/docs/guides/encoding-settings/README.md
@@ -35,4 +35,4 @@ public class MyService
 }
 ```
 
-This will ensure that the settings you have set for the Unicode ranges will also apply to your own code.
+This will ensure that the settings you have set for the Unicode ranges will also apply to your own code.
diff --git a/src/docs/guides/gulp-pipeline/README.md b/src/docs/guides/gulp-pipeline/README.md
@@ -17,17 +17,17 @@ In Visual Studio you will find these files in **Solution Explorer** in a solutio
 
 There are several reasons why the pipeline has been implemented at the solution level rather than in each extension that needs to process client-side assets.
 
-* Current and future can share the existing pipeline logic instead of having to reinvent it.
-* Only one copy of the necessary Node.js packages needs to be downloaded and stored alongside the codebase.
-* Keeping Node package folders (`node_modules`) anywhere inside the `OrchardCore.Cms.Web` project causes their contents to be included when publishing Orchard for deployment which would increase the size of the deployment package by orders of magnitude even though these files are only useful at development time.
+- Current and future can share the existing pipeline logic instead of having to reinvent it.
+- Only one copy of the necessary Node.js packages needs to be downloaded and stored alongside the codebase.
+- Keeping Node package folders (`node_modules`) anywhere inside the `OrchardCore.Cms.Web` project causes their contents to be included when publishing Orchard for deployment which would increase the size of the deployment package by orders of magnitude even though these files are only useful at development time.
 
 The client-side asset pipeline is not configured by default to be invoked automatically when opening or building Orchard Core. To minimize build time and make it as easy as possible to get started with Orchard Core, all built-in modules and themes in Orchard Core are kept in source control with their processed output files included. This means you don't have to activate and run the client-side asset pipeline to build or run Orchard Core out of the box. You only need to run the client-side asset pipeline if you make changes to these assets, or wish to use it to process assets in your own extensions.
 
 # Getting started
 
 ## Installing prerequisites
 
-The client-side asset pipeline requires Node.js to be installed. If you are using Visual Studio 2022 or later, Node.js is typically already installed as part of Visual Studio. If you are not using Visual Studio, or if you selected not to include Node.js when installing Visual Studio, you will need to install Node.js manually from https://nodejs.org.
+The client-side asset pipeline requires Node.js to be installed. If you are using Visual Studio 2022 or later, Node.js is typically already installed as part of Visual Studio. If you are not using Visual Studio, or if you selected not to include Node.js when installing Visual Studio, you will need to install Node.js manually from <https://nodejs.org>.
 
 Next you will need to use NPM to install all the packages the client-side asset pipeline needs, including Gulp itself. Using the command line, navigate to the Orchard Core solution folder and execute the command `npm install`, which will install all dependencies referenced in the `package.json` file. In Visual Studio 2022 or later, you can instead simply open the `package.json` file and save it without making any changes - this will trigger an automatic `npm install` behind the scenes.
 
@@ -145,8 +145,8 @@ When executing the **build** or **rebuild** task, the asset pipeline will perfor
 
 After the **build** task has executed your extension's `Styles` folder will contain two files:
 
-* `Styles.css` (non-minified with inline source maps)
-* `Styles.min.css` (minified)
+- `Styles.css` (non-minified with inline source maps)
+- `Styles.min.css` (minified)
 
 Once these output asset files have been generated you can reference them from Razor views just as you normally wolud using the Orchard Core resource manager, either by declaring them in a resource manifest class and requiring them using one of the `Require()` methods or by including them by path using one of the `Include()` methods.
 
@@ -280,36 +280,36 @@ For example you can specify both `.less` and `.css` input assets in a group targ
 
 The following file types are supported as stylesheet input assets:
 
-* LESS (`.less`)
-* SASS (`.sass`)
-* SCSS (`.scss`)
-* Plain CSS (`.css`)
+- LESS (`.less`)
+- SASS (`.sass`)
+- SCSS (`.scss`)
+- Plain CSS (`.css`)
 
 The following tasks are performed on stylesheet assets:
 
-* LESS/SASS transpilation
-* Vendor prefix normalization
-* Inline source map generation (unless disabled)
-* File header generation
-* Line ending normalization
-* Bundling (unless disabled)
-* Minification
+- LESS/SASS transpilation
+- Vendor prefix normalization
+- Inline source map generation (unless disabled)
+- File header generation
+- Line ending normalization
+- Bundling (unless disabled)
+- Minification
 
 ### Script assets
 
 The following file types are supported as script input assets:
 
-* TypeScript (`*.ts`, `*.jsx`)
-* Plain JavaScript (`*.js`)
+- TypeScript (`*.ts`, `*.jsx`)
+- Plain JavaScript (`*.js`)
 
 The following tasks are performed on script assets:
 
-* TypeScript transpilation
-* Inline source map generation (unless disabled)
-* File header generation
-* Line ending normalization
-* Bundling (unless disabled)
-* Minification
+- TypeScript transpilation
+- Inline source map generation (unless disabled)
+- File header generation
+- Line ending normalization
+- Bundling (unless disabled)
+- Minification
 
 Note: All input script assets are processed through the TypeScript transpiler, also plain JavaScript `.js` files. This means the asset pipeline will throw errors for obvious syntactical errors in plain JavaScript files. This should generally be considered an advantage as JavaScript errors can be caught at build time rather than at runtime.
 
@@ -337,8 +337,8 @@ An array of additional files to be monitored for changes. Paths are relative to
 
 By default, when using a glob to specify input assets and using the `@` character in the output file path to bypass bundling, output files are generated in the same relative location as their corresponding input assets relative to the first glob in the input pattern. For example, assuming you have the following input assets:
 
-* `Assets/Pages/PageStyles.less`
-* `Assets/Widgets/LoginWidget/Login.less`
+- `Assets/Pages/PageStyles.less`
+- `Assets/Widgets/LoginWidget/Login.less`
 
 Given the following asset group definition:
 
@@ -353,29 +353,29 @@ Given the following asset group definition:
 
 The default behavior of the asset pipeline would generate the following output files:
 
-* `Styles/Pages/PageStyles.css`
-* `Styles/Pages/PageStyles.min.css`
-* `Styles/Widgets/LoginWidget/Login.css`
-* `Styles/Widgets/LoginWidget/Login.min.css`
+- `Styles/Pages/PageStyles.css`
+- `Styles/Pages/PageStyles.min.css`
+- `Styles/Widgets/LoginWidget/Login.css`
+- `Styles/Widgets/LoginWidget/Login.min.css`
 
 This may not always be the desired behavior. The `flatten` property can be set to `true` to have the asset pipeline flatten the output folder structure and disregard the relative locations of the input asset files. In this case, setting `flatten` to `true` would instead produce the following two output files:
 
-* `Styles/PageStyles.css`
-* `Styles/PageStyles.min.css`
-* `Styles/Login.css`
-* `Styles/Login.min.css`
+- `Styles/PageStyles.css`
+- `Styles/PageStyles.min.css`
+- `Styles/Login.css`
+- `Styles/Login.min.css`
 
 ### `separateMinified`
 
 By default, minified output files are generated alongside their non-minified siblings with a `.min` filename extension:
 
-* `Styles/SomeStyles.css`
-* `Styles/SomeStyles.min.css`    
+- `Styles/SomeStyles.css`
+- `Styles/SomeStyles.min.css`
 
 In some cases, such as when using a runtime module loader, it can be useful to place minified output files in a subfolder instead of suffixing their filenames. This allows you to simply configure a different base path for the module loader depending on execution mode (i.e. debug vs. release) rather than having to declare every resource differently. Setting the `separateMinified` option property to `true` will result in the following alternative output structure:
 
-* `Styles/SomeStyles.css`
-* `Styles/min/SomeStyles.css`
+- `Styles/SomeStyles.css`
+- `Styles/min/SomeStyles.css`
 
 ### `typeScriptOptions`
 
@@ -399,17 +399,17 @@ However, when developing an extension for internal use you may also consider the
 
 This approach has a couple of advantages:
 
-* Smaller version control footprint
-* No risk of inconsistent/stale output assets due to forgetting to rebuild them or commit their changes to version control
+- Smaller version control footprint
+- No risk of inconsistent/stale output assets due to forgetting to rebuild them or commit their changes to version control
 
 When using this approach, the `Styles` and `Scripts` folders in your extension will always remain empty in Solution Explorer although they will contain the output files on disk, and you will typically configure a Gulp task binding to ensure that client-side assets are always built when the solution is built in Visual Studio. If using an automated build system you will also typically add a step to your build script to ensure the **build** or **rebuild** task is executed as part of the build.
 
 ## Including custom extension folders
 
 Orchard Core has the ability to load extensions from other folders besides the `OrchardCore.Modules` and `OrchardCore.Themes` folders. If your extension is stored and loaded from such a custom location, the client-side asset pipeline will not automatically detect your asset manifest. This is because, by default, it only looks for `Assets.json` files in folders under these locations:
 
-* `OrchardCore.Modules/`
-* `OrchardCore.Themes/`
+- `OrchardCore.Modules/`
+- `OrchardCore.Themes/`
 
 To add your custom location to be scanned for asset manifests, follow these steps:
 
@@ -424,11 +424,11 @@ var assetManifestPaths = glob.sync("./src/OrchardCore.{Modules,Themes}/*/Assets.
 var customThemePaths = glob.sync("AnotherLocation/MyCompanyThemes/*/Assets.json"); // Custom location!
 assetManifestPaths = assetManifestPaths.concat(customThemePaths);
 ```
-    
+
 4. Save and close the file.
-   
+
 The Orchard Core development team is investigating ways to automate this process.
 
 # Evolution of the client-side asset pipeline
 
-For those interested in the history behind the client-side asset pipeline, you can find the initial discussion with reasons for its development and proposed solutions in [issue #5450](https://github.com/OrchardCMS/Orchard/issues/5450).
+For those interested in the history behind the client-side asset pipeline, you can find the initial discussion with reasons for its development and proposed solutions in [issue #5450](https://github.com/OrchardCMS/Orchard/issues/5450).