chore(markdown-lint): setup markdownlint to lint md files and avoid having errors

.github/workflows/ci-main.yml

@@ -28,6 +28,9 @@ jobs:
       - name: Run lint
         run: npm run lint
 
+      - name: Run markdown lint
+        run: npm run lint:md
+
       - name: Run type check
         run: npm run type-check
 

.github/workflows/pr.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Run lint
         run: npm run lint
 
+      - name: Run markdown lint
+        run: npm run lint:md
+
       - name: Run type check
         run: npm run type-check
 

.markdownlint.json

@@ -0,0 +1,19 @@
+{
+  "default": true,
+  "MD001": false,
+  "MD013": false,
+  "MD024": false,
+  "MD025": false,
+  "MD026": false,
+  "MD029": false,
+  "MD033": false,
+  "MD034": false,
+  "MD036": false,
+  "MD040": false,
+  "MD041": false,
+  "MD051": false,
+  "MD052": false,
+  "MD056": false,
+  "MD059": false,
+  "MD060": false
+}

.markdownlintignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+coverage/
+example/playwright-report/
+example/node_modules/
+.next/
+.turbo/

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["DavidAnson.vscode-markdownlint"]
+}

.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+  "eslint.enable": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact"
+  ],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.fixAll.markdownlint": "explicit"
+  },
+  "eslint.workingDirectories": ["."],
+  "eslint.format.enable": true,
+  "editor.formatOnSave": true,
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.markdownlint": "explicit"
+    }
+  },
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true
+}
+

CHANGELOG.md

@@ -336,7 +336,7 @@
 - add pakistan contract details versioning (#816) [#816](https://github.com/remoteoss/remote-flows/pull/816)
 - update docs uae (#817) [#817](https://github.com/remoteoss/remote-flows/pull/817)
 
-#### Chores
+####  Chores
 
 - add tests for onboarding basic information v3 (#802) [#802](https://github.com/remoteoss/remote-flows/pull/802)
 - centralize mocks (#804) [#804](https://github.com/remoteoss/remote-flows/pull/804)

DEVELOPMENT.md

@@ -7,6 +7,7 @@ This guide is for internal developers working on the `@remoteoss/remote-flows` p
 - [Getting Started](#getting-started)
 - [Development Workflow](#development-workflow)
 - [Testing](#testing)
+- [Markdown Linting](#markdown-linting)
 - [Bundle Size Management](#bundle-size-management)
 - [CI/CD](#cicd)
 - [Release Process](#release-process)
@@ -107,6 +108,64 @@ Run type checking:
 npm run type-check
 ```
 
+## Markdown Linting
+
+We use [markdownlint](https://github.com/DavidAnson/markdownlint) to maintain consistent markdown formatting across documentation.
+
+### Commands
+
+```bash
+# Check markdown files for issues
+npm run lint:md
+
+# Auto-fix markdown issues
+npm run lint:md:fix
+```
+
+### Configuration
+
+Markdownlint is configured in `.markdownlint.json`. We've disabled certain rules to preserve intentional formatting:
+
+**Disabled Rules:**
+
+- **MD001** (heading-increment): Allow headings to skip levels (e.g., `# → ###`)
+- **MD013** (line-length): No maximum line length enforcement (allows long URLs)
+- **MD024** (no-duplicate-heading): Allow duplicate headings (needed for CHANGELOG with repeated "Features", "Fixes" per version)
+- **MD025** (single-title): Allow multiple H1 headings (READMEs have "Table of Contents" as second H1)
+- **MD026** (no-trailing-punctuation): Allow punctuation in headings (e.g., "What:")
+- **MD029** (ol-prefix): Allow any list numbering style (preserves 1/2/3 instead of changing to 1/1/1)
+- **MD033** (no-inline-html): Allow HTML in markdown (common in GitHub markdown)
+- **MD034** (no-bare-urls): Allow URLs without brackets
+- **MD036** (no-emphasis-as-heading): Allow bold/italic instead of headings
+- **MD040** (fenced-code-language): Don't require language on code blocks
+- **MD041** (first-line-heading): Don't require first line to be H1 (files may start with badges)
+- **MD051** (link-fragments): Don't validate link fragment targets
+- **MD052** (reference-links-images): Don't require reference-style link definitions
+- **MD056** (table-column-count): Don't enforce consistent column counts
+- **MD059** (descriptive-link-text): Allow "here", "click here" as link text
+- **MD060** (table-column-style): Don't enforce table pipe alignment
+
+**Enforced Rules (Important):**
+
+- **MD018** (no-missing-space-atx): Require space after hash (`##Heading` → `## Heading`)
+- **MD009**: No trailing spaces at end of lines
+- **MD012**: No multiple consecutive blank lines
+- **MD022**: Headers should be surrounded by blank lines
+- **MD031**: Fenced code blocks should be surrounded by blank lines
+- **MD047**: Files should end with a single newline
+
+### Editor Integration
+
+The `.vscode/settings.json` file configures auto-fix on save for markdown files. When you save a `.md` file:
+
+- Markdownlint automatically fixes whitespace issues
+- Trailing whitespace is trimmed
+- A final newline is added
+
+### CI Integration
+
+Markdown linting runs in CI pipelines (`.github/workflows/pr.yml` and `ci-main.yml`). PRs will fail if markdown files have formatting issues.
+
 ## Bundle Size Management
 
 We have automated bundle size tracking to ensure the package stays performant.

docs/BUNDLE_SIZE_BADGE_SETUP.md

@@ -24,6 +24,7 @@ The bundle size badge system:
 2. Create a **public** gist with:
    - **Filename**: `bundle-size.json`
    - **Content**: (Initial placeholder data)
+
    ```json
    {
      "schemaVersion": 1,
@@ -32,6 +33,7 @@ The bundle size badge system:
      "color": "lightgrey"
    }
    ```
+
 3. Click "Create public gist"
 4. Copy the Gist ID from the URL
    - Example URL: `https://gist.github.com/username/abc123def456`
@@ -65,9 +67,11 @@ The bundle size badge system:
 
 1. Open `README.md`
 2. Find the badge line:
+
    ```markdown
    [![Bundle Size](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/remoteoss/GIST_ID/raw/bundle-size.json)](https://github.com/remoteoss/remote-flows/actions/workflows/update-badge.yml)
    ```
+
 3. Replace `GIST_ID` with your actual Gist ID
 4. Replace `remoteoss` with your GitHub username or organization name
 

docs/schema-changes/SCHEMA_CHANGES.md

@@ -57,10 +57,11 @@ Schema versions for the Contract Details step in employee onboarding flows.
 ## Version Support Matrix
 
 Track which schema versions are supported by each SDK version.
-| SDK Version | Basic Information | Contract Details |
-|-------------|-------------------|------------------|
-| 1.23.0+ | v3 (recommended) | v2 (18 countries) |
-| 1.0.0+ | v1 (legacy) | v1 (default) |
+
+| SDK Version | Basic Information | Contract Details  |
+| ----------- | ----------------- | ----------------- |
+| 1.23.0+     | v3 (recommended)  | v2 (18 countries) |
+| 1.0.0+      | v1 (legacy)       | v1 (default)      |
 
 **Legend:**