Spryker Documentation Validation

Validates and improves Spryker documentation content with automated linting, style guide compliance, and internal link format enforcement.

Overview

This skill provides comprehensive validation for Spryker documentation repositories, ensuring content meets quality standards through Vale prose linting, Markdownlint syntax checks, and adherence to Spryker-specific style guidelines. It enforces proper internal link formatting, applies appropriate tone and voice, and validates Jekyll-compatible Markdown.

Validation Workflow

When validating documentation changes:

1. **Find changed files** compared to master:

```bash

git diff master..HEAD --name-only | grep '.md'

```

2. **Run Vale** (prose linting) on each changed file:

```bash

vale --minAlertLevel=error path/to/file.md

```

3. **Run Markdownlint** (syntax checking) on each changed file:

```bash

markdownlint-cli2 path/to/file.md

```

4. **Report only ERRORS** - ignore warnings and suggestions

5. **Provide specific fixes** for each error with:

- Original markdown code

- Corrected markdown code

- Summary explaining the change

Internal Links Format

All internal relative links MUST follow this format:

```markdown

[link text](/docs/section/file.html)

```

**Rules:**

**Example:**

Documentation Standards

Grammar and Sentence Structure

Check for and fix:

Ensure:

Tone of Voice

Content must align with Google Developer Documentation Style Guide and Microsoft Style Guide:

Writing Style and Markup

**Spelling:**

**Markdown Formatting:**

- `{% info_block infoBox "Info" %}...{% endinfo_block %}` (not `> [!NOTE]`)

- `{% info_block warningBox "Warning" %}...{% endinfo_block %}`

- `{% include %}` tags as needed

Presenting Suggestions

Format all suggestions as a numbered list with three components:

1. **Original:** `[current markdown code]`

**New:** `[improved markdown code]`

**Summary:** [Brief explanation of what changed and why]

Example:

```

1. **Original:** `The system was configured by the administrator.`

**New:** `The administrator configured the system.`

**Summary:** Changed passive voice to active voice for clarity.

```

Constraints

Usage

When asked to "build" or "validate" documentation:

1. Find all changed markdown files

2. Run vale on each file

3. Run markdownlint-cli2 on each file

4. Report only errors (not warnings)

5. Suggest specific fixes for each error

6. Check and fix internal link format

7. Validate against Documentation Standards

8. Present only amendments (do not show "no change" items)