Add markdown linting with prek and fix formatting

.github/workflows/deploy.yml

@@ -22,13 +22,32 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  # Lint job
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli@0.45.0
+
+      - name: Lint markdown
+        run: markdownlint '**/*.md'
+
   # Build job
   build:
+    needs: lint
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-        
+
       - name: Setup uv
         uses: astral-sh/setup-uv@v5
 

.gitignore

@@ -1,3 +1,6 @@
+# Claude
+.claude/
+
 # Copyrighted study materials
 sources/
 

.markdownlint.yaml

@@ -0,0 +1,20 @@
+---
+# Markdownlint configuration for RHCSA study guide
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+default: true
+
+# Disable line length — study materials have long command examples
+MD013: false
+
+# Allow duplicate headings — repeated section titles across modules
+MD024: false
+
+# Allow inline HTML — MkDocs uses <details>, <summary>, etc.
+MD033: false
+
+# Allow emphasis as heading — used intentionally in study materials
+MD036: false
+
+# Disable table column style — tables are readable as-is
+MD060: false

.markdownlintignore

@@ -0,0 +1,4 @@
+sources/
+site/
+node_modules/
+.venv/

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+      - id: markdownlint
+        args: ["--fix"]
+        files: \.md$

CLAUDE.md

@@ -9,8 +9,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## User Context
 
 **GitHub Username**: @kraker (not stovepipe)
-**Repository**: https://github.com/kraker/rhcsa
-**GitHub Pages Site**: https://kraker.github.io/rhcsa/
+**Repository**: <https://github.com/kraker/rhcsa>
+**GitHub Pages Site**: <https://kraker.github.io/rhcsa/>
 
 CRITICAL: Always use @kraker as the GitHub username in all URLs, repository references, and documentation.
 
@@ -53,27 +53,32 @@ This is a Red Hat Certified System Administrator (RHCSA) certification study rep
 ## Lab Environment Requirements
 
 **Vagrant Configuration**: The `../vagrant/` directory provides automated lab environment provisioning:
+
 - RHEL 10 VMs with proper resource allocation and networking
 - Automated subscription registration with Red Hat Developer accounts
 - Pre-configured storage setup for LVM and filesystem labs
 - Prerequisites: Vagrant, VirtualBox, Red Hat Developer subscription
 
 **VM Usage**:
+
 - **rhel10a**: Used for user management and SELinux scenarios
 - **rhel10b**: Used for storage management scenarios (multiple disks pre-configured)
 
 ## Common Study Tasks
 
 ### Working with Study Materials
-- **Visit Documentation Site**: Browse https://kraker.github.io/rhcsa/ for organized study materials
+
+- **Visit Documentation Site**: Browse <https://kraker.github.io/rhcsa/> for organized study materials
 - **Start with RHCSA Synthesis**: Begin with comprehensive modules in `docs/rhcsa_synthesis/` for complete topic coverage
 - **Use Anki flashcards** for spaced repetition and command memorization
 - **Reference guides** in `docs/` directory for quick lookup during study
 - **Practice with Vagrant VMs** using Asghar Ghori book lab exercises
 - **Focus on hands-on** command execution and verification in lab environment
 
 ### Anki Flashcard Usage
+
 The `anki/rhcsa_deck.csv` file contains 169 essential commands organized by tags:
+
 - `user_management` - useradd, usermod, chage, groupadd
 - `permissions` - chmod, chown, file access controls
 - `systemd` - systemctl, journalctl, service management
@@ -87,6 +92,7 @@ The `anki/rhcsa_deck.csv` file contains 169 essential commands organized by tags
 ## Key RHCSA Command Categories
 
 ### Essential System Management
+
 ```bash
 # Service Management
 systemctl start/stop/enable/disable service
@@ -105,6 +111,7 @@ find / -user username -type f 2>/dev/null
 ```
 
 ### Storage and LVM
+
 ```bash
 # LVM Workflow
 pvcreate /dev/device
@@ -120,6 +127,7 @@ resize2fs /dev/device   # For ext4
 ```
 
 ### Security and SELinux
+
 ```bash
 # SELinux Management
 getenforce / setenforce 0|1
@@ -138,7 +146,8 @@ firewall-cmd --reload
 
 **CRITICAL**: Claude Code must update `COPYRIGHT_NOTICE.md` whenever adding copyrighted content to the repository.
 
-### When Adding New Copyrighted Materials:
+### When Adding New Copyrighted Materials
+
 1. **Read COPYRIGHT_NOTICE.md first** to understand current copyright inventory
 2. **Add new materials to `sources/` directory** (gitignored)
 3. **Update COPYRIGHT_NOTICE.md** with:
@@ -149,15 +158,41 @@ firewall-cmd --reload
 4. **Verify .gitignore excludes the new content**
 5. **Never commit copyrighted content to git repository**
 
-### Content Classification:
+### Content Classification
+
 - **Original Work**: Content created for this repository → `docs/` directory (tracked)
 - **Copyrighted Materials**: Books, PDFs, images from external sources → `sources/` directory (not tracked)
 - **Derived Content**: Analysis or summaries of copyrighted works → `sources/` directory (not tracked)
 
+## Markdown Style Guide
+
+When writing or editing markdown files in this repository, follow these conventions:
+
+- **4-space indentation** for all content under ordered list items (Python-Markdown requires this for list continuation after blank lines)
+- **Always specify a language** on fenced code blocks — use `bash` for commands, `text` for ASCII diagrams/decision trees
+- **Nested code fences** (e.g., heredocs that generate markdown): use `````bash` (4 backticks) for the outer fence so inner ` ``` ` don't close it
+- **Escape pipes in tables**: use `\|` inside table cells (e.g., `` `ps aux \| grep httpd` ``)
+- **MkDocs extensions**: the site uses `pymdownx.highlight` + `pymdownx.superfences` (not legacy `codehilite`)
+
+### Linting
+
+Pre-commit hooks are managed by [prek](https://prek.j178.dev/) with markdownlint:
+
+- Config: `.pre-commit-config.yaml` (markdownlint with `--fix`)
+- Rules: `.markdownlint.yaml` — disabled: MD013 (line length), MD024 (duplicate headings), MD033 (inline HTML), MD036 (emphasis as heading)
+- Ignore: `.markdownlintignore` — excludes `sources/`, `site/`, `node_modules/`, `.venv/`
+
+```bash
+prek install              # Install git hooks (one-time)
+markdownlint '**/*.md'    # Lint all markdown
+markdownlint --fix docs/  # Auto-fix issues
+prek run --all-files      # Run all hooks
+```
+
 ## Notes for Claude Code
 
 - This repository focuses on RHCSA exam preparation, not software development
-- **Documentation Site**: The repository is published as a MkDocs site at https://kraker.github.io/rhcsa/
+- **Documentation Site**: The repository is published as a MkDocs site at <https://kraker.github.io/rhcsa/>
 - When helping with study materials, emphasize practical command execution and verification
 - The study materials in `docs/` are original work and tracked in git
 - External resources in `sources/` contain copyrighted materials and are not tracked
@@ -169,26 +204,30 @@ firewall-cmd --reload
 ## Git Commit Style Guide
 
 ### Atomic Commit Principles
+
 Following [Aleksandr Hovhannisyan's atomic git commits](https://www.aleksandrhovhannisyan.com/blog/atomic-git-commits/):
 
 **Core Rule**: Each commit should represent "a single, complete unit of work" that can be independently reviewed and reverted.
 
 ### Commit Message Format
 
 **Simple Changes** (data fixes, small bug fixes):
+
 ```bash
 git commit -m "Fix malformed times in SELinux troubleshooting examples"
 git commit -m "Update Anki flashcard for ausearch command syntax"
 git commit -m "Add missing firewall commands to quick reference"
 ```
 
 **Feature Commits** (new capabilities, significant changes):
+
 ```bash
 git commit -m "Add comprehensive ausearch troubleshooting section to SELinux lab"
 git commit -m "Implement enhanced SELinux flashcards with Red Hat official syntax"
 ```
 
 **Milestone/Release Commits** (major completions):
+
 ```bash
 # Use detailed heredoc format for comprehensive changelog
 git commit -m "$(cat <<'EOF'
@@ -208,13 +247,15 @@ EOF
 ```
 
 ### Guidelines
+
 - **Present tense verbs**: "Fix", "Add", "Update", "Remove", "Implement"
 - **Component focus**: Mention what study material/system is changed
 - **Atomic scope**: One logical change per commit
 - **No fear of many commits**: Better to have 5 focused commits than 1 mixed commit
 - **Commit early and often**: Make commits as soon as a logical unit is complete
 
 ### Examples by Type
+
 - **Content fixes**: `Fix duplicate commands in storage management flashcards`
 - **Study material updates**: `Add comprehensive ausearch examples to SELinux lab`
 - **Reference enhancements**: `Implement timezone-aware examples in quick reference`
@@ -223,9 +264,9 @@ EOF
 
 ## Study Workflow Recommendations
 
-1. **Visit Documentation Site**: Browse https://kraker.github.io/rhcsa/ for organized study materials
+1. **Visit Documentation Site**: Browse <https://kraker.github.io/rhcsa/> for organized study materials
 2. **Begin with RHCSA Synthesis**: Start with `docs/rhcsa_synthesis/` for comprehensive topic coverage
 3. **Use Anki deck** (`anki/rhcsa_deck.csv`) for command memorization and quick reference
 4. **Practice with Vagrant VMs** using Asghar Ghori book lab exercises
 5. **Verify all tasks** with provided verification commands
-6. **Focus on practical application** rather than theoretical knowledge
+6. **Focus on practical application** rather than theoretical knowledge

COPYRIGHT_NOTICE.md

@@ -5,6 +5,7 @@
 This repository contains analysis and study materials derived from the following copyrighted works, all stored in the `sources/` directory (not tracked in git):
 
 ### Study Books
+
 1. **"RHCSA Red Hat Enterprise Linux 10" by Asghar Ghori** (Dec 2025 edition)
    - EPUB file: `sources/RHCSA Red Hat Enterprise Linux - Asghar Ghori.epub`
    - Converted content: `sources/asghar_ghori_rhcsa.md`
@@ -18,13 +19,14 @@ This repository contains analysis and study materials derived from the following
    - Status: Excluded from repository via .gitignore
 
 ### Official Documentation
-3. **Red Hat Enterprise Linux 9 - Using SELinux**
+
+1. **Red Hat Enterprise Linux 9 - Using SELinux**
    - PDF file: `sources/Red_Hat_Enterprise_Linux-9-Using_SELinux-en-US.pdf`
    - Publisher: Red Hat, Inc.
    - License: Likely Creative Commons or similar open license (check document)
    - Status: Excluded from repository via .gitignore
 
-4. **Red Hat Enterprise Linux for SAP Solutions 9 - Using SELinux for SAP HANA**
+2. **Red Hat Enterprise Linux for SAP Solutions 9 - Using SELinux for SAP HANA**
    - PDF file: `sources/Red_Hat_Enterprise_Linux_for_SAP_Solutions-9-Using_SELinux_for_SAP_HANA-en-US.pdf`
    - Publisher: Red Hat, Inc.
    - License: Likely Creative Commons or similar open license (check document)
@@ -43,8 +45,9 @@ The following files are original work and analysis based on the study materials:
 ## Fair Use Statement
 
 The analysis contained in this repository represents educational use of copyrighted materials under fair use doctrine for:
+
 - Personal study and exam preparation
 - Educational analysis and commentary
 - Transformation of content into study aids
 
-The original copyrighted works are not redistributed and remain protected.
+The original copyrighted works are not redistributed and remain protected.