Add docs validation (#105)

Check html, css and links in docs directory.

Author: tigrannajaryan

.github/workflows/docs-validation.yml

@@ -0,0 +1,39 @@
+name: Docs Validation
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-validation.yml'
+      - 'makefile'
+      - 'package.json'
+      - '.stylelintrc.json'
+  pull_request:
+    branches: [ main, develop ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-validation.yml'
+      - 'makefile'
+      - 'package.json'
+      - '.stylelintrc.json'
+
+jobs:
+  validate-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+
+    - name: Install docs validation dependencies
+      run: make docs-install-deps
+
+    - name: Run complete docs validation
+      run: make docs-validate

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 bin/
 .idea
+node_modules

.stylelintrc.json

@@ -0,0 +1,17 @@
+{
+  "extends": ["stylelint-config-standard"],
+  "rules": {
+    "property-no-vendor-prefix": null,
+    "selector-class-pattern": null,
+    "custom-property-pattern": null,
+    "declaration-block-single-line-max-declarations": null,
+    "color-function-notation": null,
+    "font-family-name-quotes": null,
+    "rule-empty-line-before": null,
+    "shorthand-property-no-redundant-values": null,
+    "color-function-alias-notation": null,
+    "alpha-value-notation": null,
+    "at-rule-empty-line-before": null,
+    "media-feature-range-notation": null
+  }
+}

docs/index.html

@@ -81,7 +81,7 @@ <h2>Generate Serializers</h2>
 
     <h2>Write STEF Records</h2>
     <pre><code class="language-go">// Prepare a memory buffer to write the STEF stream to.
-buf := &pkg.MemChunkWriter{}
+buf := &amp;pkg.MemChunkWriter{}
 
 // Create a Writer for the JSON-like schema
 w := jsonlike.NewWriter(buf, pkg.WriterOptions{})
@@ -102,7 +102,7 @@ <h2>Learn More</h2>
           <li><a href="https://github.com/splunk/stef">GitHub Repository</a></li>
       </ul>
     <h2>License</h2>
-    Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License 2.0</a>.</p>
+    Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License 2.0</a>.
   </main>
   <script src="https://cdn.jsdelivr.net/npm/[email protected]/prism.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/[email protected]/components/prism-go.min.js"></script>

makefile

@@ -17,7 +17,7 @@ default:
 	cd benchmarks && make
 
 .PHONY: all
-all:
+all: docs-validate
 	cd stefgen && make all
 	cd go/pkg && make all
 	cd go/grpc && make all
@@ -64,3 +64,66 @@ MODULES := go/pkg go/grpc go/otel go/pdata
 releasever: verifyver
 	echo Tagging version $(VERSION)
 	$(foreach gomod,$(MODULES),$(call exec-command,git tag $(gomod)/$(VERSION) && git push origin $(gomod)/$(VERSION)))
+
+# Docs validation targets
+.PHONY: docs-validate docs-validate-html docs-validate-css docs-check-links docs-install-deps
+
+# Validate all docs (HTML, CSS, and links)
+docs-validate: docs-validate-html docs-validate-css docs-check-links
+	@echo "✅ All docs validation checks passed!"
+
+# Validate HTML files in docs directory
+docs-validate-html:
+	@echo "🔍 Validating HTML files in docs..."
+	@cd docs && for file in *.html; do \
+		if [ -f "$$file" ] && [ "$$file" != "benchmarks.html" ]; then \
+			echo "Validating $$file..."; \
+			../node_modules/.bin/html-validate "$$file" || (echo "❌ HTML validation failed for $$file" && exit 1); \
+		elif [ -f "$$file" ] && [ "$$file" = "benchmarks.html" ]; then \
+			echo "Skipping validation for $$file (excluded)"; \
+		fi; \
+	done
+	@echo "✅ HTML validation complete"
+
+# Validate CSS files in docs directory
+docs-validate-css:
+	@echo "🔍 Validating CSS files in docs..."
+	@cd docs && for file in *.css; do \
+		if [ -f "$$file" ]; then \
+			echo "Validating $$file..."; \
+			../node_modules/.bin/stylelint "$$file" --config-basedir .. || (echo "❌ CSS validation failed for $$file" && exit 1); \
+		fi; \
+	done
+	@echo "✅ CSS validation complete"
+
+# Check links in HTML files
+docs-check-links:
+	@for file in docs/*.html; do \
+		if [ -f "$$file" ]; then \
+			echo "Checking links in $$(basename $$file)..."; \
+			./node_modules/.bin/markdown-link-check "$$file" --quiet || true; \
+			echo "  ✅ Link check completed for $$(basename $$file)"; \
+		fi; \
+	done
+	@echo "✅ Link checking complete"
+
+# Install npm-based validation dependencies for docs
+docs-install-deps:
+	@echo "📦 Installing npm-based validation dependencies at top level..."
+	@if ! command -v npm >/dev/null 2>&1; then \
+		echo "❌ npm not found. Please install Node.js and npm first."; \
+		echo "Visit: https://nodejs.org/"; \
+		exit 1; \
+	fi
+	@if [ ! -f package.json ]; then \
+		echo "Creating package.json..."; \
+		npm init -y; \
+	fi
+	@echo "Installing HTML validation tools..."
+	@npm install html-validate
+	@echo "Installing CSS validation tools..."
+	@npm install stylelint stylelint-config-standard
+	@echo "Installing link checking tools..."
+	@npm install markdown-link-check
+	@echo "✅ All docs dependencies installed successfully!"
+	@echo "Tools installed in ./node_modules/.bin/"