From 420cfdd45d38a0d9d0847ddb20cc8adadd8ee79e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Fri, 20 Mar 2026 17:30:10 +0100 Subject: [PATCH 1/2] Added markdownlint2 for detecting Markdown formatting issues --- .github/workflows/build.yaml | 12 ++++++ .markdownlint-cli2.yaml | 19 ++++++++++ README.md | 37 +++++++++++++------ .../back_office_menus/back_office_menus.md | 2 +- .../project_organization/bundles.md | 4 +- .../event_reference/twig_component_events.md | 4 +- docs/permissions/policies.md | 2 +- .../api_reference/recommendation_api.md | 2 +- .../ez_platform_v3.0_deprecations.md | 4 +- docs/release_notes/ibexa_dxp_v3.2.md | 2 +- docs/release_notes/ibexa_dxp_v4.0.md | 2 +- docs/release_notes/ibexa_dxp_v4.1.md | 2 +- docs/templating/components.md | 2 +- package.json | 4 +- 14 files changed, 72 insertions(+), 26 deletions(-) create mode 100644 .markdownlint-cli2.yaml diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 438b94da7a..982a2245a3 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -65,6 +65,18 @@ jobs: exit 1 fi + markdownlint: + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + + steps: + - uses: actions/checkout@v4 + + - name: Run markdownlint + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + globs: "docs/**/*.md" + vale-check: runs-on: ubuntu-latest if: github.event_name == 'pull_request' diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000000..2c1a1304e5 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,19 @@ +config: + default: false + heading-style: consistent + list-indent: true + no-reversed-links: true + no-missing-space-atx: true + heading-start-left: true + no-multiple-space-blockquote: true + no-blanks-blockquote: true + hr-style: true + no-empty-links: true + code-fence-style: backtick + strong-style: asterisk + table-pipe-style: + style: leading_and_trailing + +ignores: + - "docs/snippets/**" + - "docs/index.md" diff --git a/README.md b/README.md index 497e15544f..81daf33367 100644 --- a/README.md +++ b/README.md @@ -20,18 +20,9 @@ If you'd like to see Ibexa DXP in your language, you can [contribute to the tran ### Contribute to API reference -The REST API Reference is located in the `docs/api/rest_api/rest_api_reference/rest_api_reference.html` -file, which is generated automatically by the RAML2HTML tool. -It is based on `*.raml` files located in the `docs/api/rest_api/rest_api_reference/input` directory that you can edit in your editor/IDE. - -After you modify relevant files in the input folder, you can generate an HTML file from repository root (this step can also be performed by one of the Tech Writers during PR review): - -`php tools/raml2html/raml2html.php build --non-standard-http-methods=COPY,MOVE,PUBLISH,SWAP -t default -o docs/api/rest_api/rest_api_reference/output/ docs/api/rest_api/rest_api_reference/input/ibexa.raml` - -In case of errors, look for mistakes in the RAML file, for example, double apostrophes. -Move `rest_api_reference.html` from the output folder to `docs/api/rest_api/rest_api_reference/` root. - -See `tools/raml2html/README.md` for more information. +The REST API Reference is located in the `docs/api/rest_api/rest_api_reference/` directory. +It is based on an OpenAPI specification (`openapi.yaml` / `openapi.json`) generated from the Ibexa DXP source code. +To contribute to the REST API reference, you must modify the source code annotations directly. ## Build and preview documentation @@ -53,6 +44,28 @@ of the command. ## Testing the code samples +### markdownlint + +This repository uses [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) to check Markdown formatting, including table syntax. + +Install dependencies: + +```bash +yarn install +``` + +Run the linter: + +```bash +yarn markdownlint +``` + +Some issues can be fixed automatically: + +```bash +yarn markdownlint --fix +``` + ### PHPStan This repository uses PHPStan to test the code samples. To run the tests locally execute the commands below: diff --git a/docs/administration/back_office/back_office_menus/back_office_menus.md b/docs/administration/back_office/back_office_menus/back_office_menus.md index a6fc33cc44..5ae4e704bb 100644 --- a/docs/administration/back_office/back_office_menus/back_office_menus.md +++ b/docs/administration/back_office/back_office_menus/back_office_menus.md @@ -36,7 +36,7 @@ You can listen to the following events: || `ConfigureMenuEvent::CONTENT_CREATE_SIDEBAR_RIGHT` | || `ConfigureMenuEvent::CONTENT_SIDEBAR_LEFT` | | Trash | `ConfigureMenuEvent::TRASH_SIDEBAR_RIGHT` | -| Section | `ConfigureMenuEvent::SECTION_EDIT_SIDEBAR_RIGHT` +| Section | `ConfigureMenuEvent::SECTION_EDIT_SIDEBAR_RIGHT` | || `ConfigureMenuEvent::SECTION_CREATE_SIDEBAR_RIGHT` | | Policies and permissions | `ConfigureMenuEvent::POLICY_EDIT_SIDEBAR_RIGHT` | || `ConfigureMenuEvent::POLICY_CREATE_SIDEBAR_RIGHT` | diff --git a/docs/administration/project_organization/bundles.md b/docs/administration/project_organization/bundles.md index be3c393e9a..25a1e7ad06 100644 --- a/docs/administration/project_organization/bundles.md +++ b/docs/administration/project_organization/bundles.md @@ -124,8 +124,8 @@ To remove a bundle (either one you created yourself, or an out-of-the-box one th |ibexa/experience|Metapackage for Symfony Flex-based [[= product_name =]] Experience installation| |ibexa/cart|Main store functionalities| |ibexa/checkout|Store checkout functionality| -|ibexa/corporate-account-commerce-bridge|Additional functionality for [corporate accounts](corporate_admin_panel.md| -|ibexa/discounts|Adds [discounts](discounts.md) functionality|feature +|ibexa/corporate-account-commerce-bridge|Additional functionality for [corporate accounts](corporate_admin_panel.md)| +|ibexa/discounts|Adds [discounts](discounts.md) functionality| |ibexa/discounts-codes|Adds the possibility to use discount codes with the [Discounts](discounts.md) functionality| |ibexa/storefront|A storefront starting kit| |ibexa/order-management|Order management| diff --git a/docs/api/event_reference/twig_component_events.md b/docs/api/event_reference/twig_component_events.md index 0d0edbe143..b1dfb368aa 100644 --- a/docs/api/event_reference/twig_component_events.md +++ b/docs/api/event_reference/twig_component_events.md @@ -12,5 +12,5 @@ Use the events to hook into the rendering process of [Twig Components](component | Event | Dispatched by | Description | |---|---|---| -|`RenderGroupEvent`| `\Ibexa\TwigComponents\Component\Renderer\DefaultRenderer::renderGroup()` | Dispatched before a Component group is rendered -|`RenderSingleEvent`| `\Ibexa\TwigComponents\Component\Renderer\DefaultRenderer::renderSingle()` |Dispatched before a single Component is rendered +|`RenderGroupEvent`| `\Ibexa\TwigComponents\Component\Renderer\DefaultRenderer::renderGroup()` | Dispatched before a Component group is rendered | +|`RenderSingleEvent`| `\Ibexa\TwigComponents\Component\Renderer\DefaultRenderer::renderSingle()` |Dispatched before a single Component is rendered | diff --git a/docs/permissions/policies.md b/docs/permissions/policies.md index c54fed2812..396caa67a7 100644 --- a/docs/permissions/policies.md +++ b/docs/permissions/policies.md @@ -247,7 +247,7 @@ The [discount](discounts.md) policies decide which actions can be executed by gi | Module | Function | Effect | Possible limitations | |----------------------|-----------------------|--------------------------------------------------------------------------|----------------------| -| `content` | `share` | share content drafts with internal and external users through [collaborative editing](collaborative_editing.md) |[Owner](limitation_reference.md#collaborative-editing-owner-limitation)
[PublicLink](limitation_reference.md#collaborative-editing-publiclink-limitation)
[Scope](limitation_reference.md#collaborative-editing-scope-limitation) +| `content` | `share` | share content drafts with internal and external users through [collaborative editing](collaborative_editing.md) |[Owner](limitation_reference.md#collaborative-editing-owner-limitation)
[PublicLink](limitation_reference.md#collaborative-editing-publiclink-limitation)
[Scope](limitation_reference.md#collaborative-editing-scope-limitation) | | `rte` | `edit` | use [Real-time editing](collaborative_editing_guide.md#real-time-editing) | diff --git a/docs/personalization/api_reference/recommendation_api.md b/docs/personalization/api_reference/recommendation_api.md index 2733aa35f9..42727e5e43 100644 --- a/docs/personalization/api_reference/recommendation_api.md +++ b/docs/personalization/api_reference/recommendation_api.md @@ -95,7 +95,7 @@ For more information, see [Submodels]([[= user_doc =]]/personalization/recommend If you have configured segments, you can use them in the recommendation model. Pass the following parameter to request recommendations for a specific segment or segment group. -Parameter|Example|Description|Value| +|Parameter|Example|Description|Value| |---|---|---|---| |`segments`|`&segments=7,8,10,11`|ID from segment group management|string| diff --git a/docs/release_notes/ez_platform_v3.0_deprecations.md b/docs/release_notes/ez_platform_v3.0_deprecations.md index cb7f8aa158..a53c0491b1 100644 --- a/docs/release_notes/ez_platform_v3.0_deprecations.md +++ b/docs/release_notes/ez_platform_v3.0_deprecations.md @@ -373,7 +373,7 @@ The following event names have been changed: |`openUdw`|`ez-open-udw`| |`updateFieldName`|`ez-update-field-name`| |`fbFormBuilderLoaded`|`ez-form-builder-loaded`| -|`fbFormBuilderUnloaded`|`ez-form-builder-unloaded` +|`fbFormBuilderUnloaded`|`ez-form-builder-unloaded`| ## ezplatform-http-cache @@ -820,7 +820,7 @@ The following namespaces have been changed: |Namespace|Former location|New location| |---------|------------|---------------| |`FieldData`|`EzSystems\RepositoryForms\Data\Content\`|`EzSystems\EzPlatformContentForms\Data\Content\`| -|`FieldValueFormMapperInterface`|`EzSystems\RepositoryForms\FieldType\`|`EzSystems\EzPlatformContentForms\FieldType\` +|`FieldValueFormMapperInterface`|`EzSystems\RepositoryForms\FieldType\`|`EzSystems\EzPlatformContentForms\FieldType\`| ## ezplatform-rest diff --git a/docs/release_notes/ibexa_dxp_v3.2.md b/docs/release_notes/ibexa_dxp_v3.2.md index 6d145b05b8..362635b839 100644 --- a/docs/release_notes/ibexa_dxp_v3.2.md +++ b/docs/release_notes/ibexa_dxp_v3.2.md @@ -112,4 +112,4 @@ to [get object states and object state groups](https://doc.ibexa.co/en/latest/ap | Ibexa Platform | [[= product_name =]] | [[= product_name_com =]] | |--------------|------------|------------| -| [Ibexa Platform v3.2.0](https://github.com/ezsystems/ezplatform/releases/tag/v3.2.0) | [[[= product_name =]] v3.2.0](https://github.com/ezsystems/ezplatform-ee/releases/tag/v3.2.0) | [[[= product_name_com =]] v3.2.0](https://github.com/ezsystems/ezcommerce/releases/tag/v3.2.0) +| [Ibexa Platform v3.2.0](https://github.com/ezsystems/ezplatform/releases/tag/v3.2.0) | [[[= product_name =]] v3.2.0](https://github.com/ezsystems/ezplatform-ee/releases/tag/v3.2.0) | [[[= product_name_com =]] v3.2.0](https://github.com/ezsystems/ezcommerce/releases/tag/v3.2.0) | diff --git a/docs/release_notes/ibexa_dxp_v4.0.md b/docs/release_notes/ibexa_dxp_v4.0.md index 752c877cf6..0870e0928d 100644 --- a/docs/release_notes/ibexa_dxp_v4.0.md +++ b/docs/release_notes/ibexa_dxp_v4.0.md @@ -119,4 +119,4 @@ for full details of changes and how they influence your project. | [[= product_name_content =]] | [[= product_name_exp =]] | [[= product_name_com =]] | |--------------|------------|------------| -| [[[= product_name_content =]] v4.0](https://github.com/ibexa/content/releases/tag/v4.0.0) | [[[= product_name_exp =]] v4.0](https://github.com/ibexa/experience/releases/tag/v4.0.0) | [[[= product_name_com =]] v4.0](https://github.com/ibexa/commerce/releases/tag/v4.0.0) +| [[[= product_name_content =]] v4.0](https://github.com/ibexa/content/releases/tag/v4.0.0) | [[[= product_name_exp =]] v4.0](https://github.com/ibexa/experience/releases/tag/v4.0.0) | [[[= product_name_com =]] v4.0](https://github.com/ibexa/commerce/releases/tag/v4.0.0) | diff --git a/docs/release_notes/ibexa_dxp_v4.1.md b/docs/release_notes/ibexa_dxp_v4.1.md index 2ceede15e5..0f89430db8 100644 --- a/docs/release_notes/ibexa_dxp_v4.1.md +++ b/docs/release_notes/ibexa_dxp_v4.1.md @@ -88,4 +88,4 @@ which prevents multiple processes from executing the same migration and causing | [[= product_name_content =]] | [[= product_name_exp =]] | [[= product_name_com =]] | |--------------|------------|------------| -| [[[= product_name_content =]] v4.1](https://github.com/ibexa/content/releases/tag/v4.1.0) | [[[= product_name_exp =]] v4.1](https://github.com/ibexa/experience/releases/tag/v4.1.0) | [[[= product_name_com =]] v4.1](https://github.com/ibexa/commerce/releases/tag/v4.1.0) +| [[[= product_name_content =]] v4.1](https://github.com/ibexa/content/releases/tag/v4.1.0) | [[[= product_name_exp =]] v4.1](https://github.com/ibexa/experience/releases/tag/v4.1.0) | [[[= product_name_com =]] v4.1](https://github.com/ibexa/commerce/releases/tag/v4.1.0) | diff --git a/docs/templating/components.md b/docs/templating/components.md index 42521ad0b4..8f5bf962ae 100644 --- a/docs/templating/components.md +++ b/docs/templating/components.md @@ -73,7 +73,7 @@ You can use an unique group name when creating a Twig Component to create your o | [HTML](https://github.com/ibexa/twig-components/blob/main/src/lib/Component/HtmlComponent.php) | Renders static HTML |`html` | | [Menu](https://github.com/ibexa/twig-components/blob/main/src/lib/Component/MenuComponent.php) | Renders a [menu](https://symfony.com/bundles/KnpMenuBundle/current/index.html) |`menu` | | [Script](https://github.com/ibexa/twig-components/blob/main/src/lib/Component/ScriptComponent.php) | Renders a [`