>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3579480. --> Reported by: [abhisekmazumdar](https://www.drupal.org/user/3557964) Related to !1325 >>> <p>[Tracker]<br> <strong>Update Summary: </strong>[One-line status update for stakeholders]<br> <strong>Short Description: </strong>[One-line issue summary for stakeholders]<br> <strong>Check-in Date: </strong>MM/DD/YYYY<br> <em>Metadata is used by the <a href="https://www.drupalstarforge.ai/" title="AI Tracker">AI Tracker.</a> Docs and additional fields <a href="https://www.drupalstarforge.ai/ai-dashboard/docs" title="AI Issue Tracker Documentation">here</a>.</em><br> [/Tracker]</p> <h2>Problem/Motivation</h2> <p>MkDocs is strict about certain Markdown formatting rules that other renderers silently ignore. The most common example is requiring a blank line before a bullet list:</p> <pre><pre>Some text paragraph here<br>* This will break in MkDocs</pre></pre><p>Must be written as:</p> <pre><pre>Some text paragraph here<br><br>* This renders correctly</pre></pre><p>These issues are only caught when the <code>pages</code> CI job runs on a release branch, meaning they can accumulate undetected across many MRs. See <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/ai/issues/3577185" title="Status: Closed (fixed)">#3577185: Fix Documentation for 1.2.x and 1.3.x branches</a></span> for a recent example.</p> <h2>Proposed resolution</h2> <p>Add a dedicated CI job that validates the documentation build on every MR that touches <code>docs/**/*</code> or <code>mkdocs.yml</code>, so formatting errors are caught before merge rather than after.</p> <p>Two approaches are worth discussing:</p> <p><strong>Option 1: <code>mkdocs build --strict</code> (recommended)</strong></p> <p>Add a CI job that runs <code>mkdocs build --strict</code>. The <code>--strict</code> flag promotes MkDocs warnings to errors. This catches any rendering issue, not just list spacing, and stays in sync with MkDocs as it evolves. The required pip dependencies are already known from the existing <code>pages</code> job.</p> <p><strong>Option 2: Regex lint script</strong></p> <p>Add a shell script under <code>scripts/</code> that greps for the specific pattern: a non-blank text line immediately followed by a list item (<code>*</code> or <code>-</code>) with no blank line in between. Faster to run and requires no pip install in CI.</p> <h2>Remaining tasks</h2> <ul> <li>Agree on preferred approach</li> <li>Add the CI job to <code>.gitlab-ci.yml</code></li> <li>Add lint script to <code>scripts/</code> if going with Option 2</li> <li>Fix any existing violations surfaced by the new check which I feel already done in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/ai/issues/3577185" title="Status: Closed (fixed)">#3577185: Fix Documentation for 1.2.x and 1.3.x branches</a></span></li> </ul> <p>[ x ] AI Assisted Issue<br> This issue was generated with AI assistance, but was reviewed and refined by the creator.</p> <p>[ ] AI Assisted Code<br> This code was mainly generated by a human, with AI autocompleting or parts AI generated, but under full human supervision.</p> <p>[ ] AI Generated Code<br> This code was mainly generated by an AI with human guidance, and reviewed, tested, and refined by a human.</p> <p>[ ] Vibe Coded<br> This code was generated by an AI and has only been functionally tested.</p>