docs: add markdownlint, formatting improvements

evansims · evansims · commit 0fa061313eff · 2025-12-03T22:20:20.000-06:00
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -0,0 +1,6 @@
+# markdownlint-cli2 configuration
+# https://github.com/DavidAnson/markdownlint-cli2
+
+ignores:
+  - "target/**"
+  - "node_modules/**"
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,32 @@
+# markdownlint configuration for InferaDB Management
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# Disable line length - not practical for technical docs with code, tables, URLs
+MD013: false
+
+# Allow duplicate headings in different sections (common in API docs: Request/Response)
+MD024:
+  siblings_only: true
+
+# Allow emphasis as pseudo-headings for inline section labels
+MD036: false
+
+# Require language on fenced code blocks
+MD040: true
+
+# Table formatting - disable strict alignment (prettier handles this)
+MD058: false
+MD060: false
+
+# Allow inline HTML when needed
+MD033: false
+
+# Allow trailing punctuation in headings (e.g., "What is IPL?")
+MD026: false
+
+# Allow multiple blank lines (sometimes useful for visual separation)
+MD012: false
+
+# Allow hard tabs in code blocks
+MD010:
+  code_blocks: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -122,7 +122,7 @@ mod tests {
 
 Follow [Conventional Commits](https://www.conventionalcommits.org/):
 
-```
+```text
 <type>(<scope>): <subject>
 
 <body>
@@ -142,7 +142,7 @@ Types:
 
 Examples:
 
-```
+```text
 feat(auth): implement password authentication
 
 Add password-based authentication with Argon2id hashing.
@@ -151,7 +151,7 @@ Includes rate limiting and session management.
 Closes #123
 ```
 
-```
+```text
 fix(storage): handle FoundationDB connection timeout
 
 Add retry logic with exponential backoff for FDB connections.
diff --git a/Makefile b/Makefile
@@ -75,7 +75,7 @@ format: ## Format code (Prettier, Taplo, markdownlint, rustfmt)
 	@$(PRETTIER) --write "**/*.{md,yml,yaml,json}" --log-level warn || true
 	@$(MARKDOWNLINT) --fix "**/*.md" || true
 	@$(TAPLO) fmt || true
-	@$(CARGO) fmt --all
+	@$(CARGO) +nightly fmt --all
 	@echo "✅ Formatting complete!"
 
 lint: ## Run linters (clippy, markdownlint)
diff --git a/NOTICE.md b/NOTICE.md
@@ -18,21 +18,21 @@ Under the terms of this license:
 
 ---
 
-### **Trademarks**
+## Trademarks
 
 "InferaDB" and the InferaDB logo are trademarks of the InferaDB Project.
 No right, title, or interest in these trademarks is granted under this license.
 
 ---
 
-### **Third-Party Components**
+## Third-Party Components
 
 This project may include open-source dependencies governed by their respective licenses.
 A complete list of third-party components and their licenses can be found in `THIRD_PARTY_NOTICES.md` (to be added as the project evolves).
 
 ---
 
-### **Summary**
+## Summary
 
 InferaDB is developed and maintained by the InferaDB Project to advance the state of fine-grained authorization and distributed access control.
 While the software is source-available, its use in commercial SaaS offerings requires prior authorization.
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ cargo run --bin inferadb-management
 
 Built in Rust with pluggable storage:
 
-```
+```text
 infera-management        # Main binary
 ├── infera-management-api      # REST/gRPC handlers
 ├── infera-management-core     # Business logic, entities, repositories
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -63,7 +63,7 @@ observability:
 
 You should see output like:
 
-```
+```text
 2025-11-18T10:00:00.000Z INFO  Starting InferaDB Management API
 2025-11-18T10:00:00.123Z INFO  HTTP server listening on 127.0.0.1:3000
 2025-11-18T10:00:00.456Z INFO  gRPC server listening on 127.0.0.1:3001
diff --git a/docs/overview.md b/docs/overview.md
@@ -2323,7 +2323,7 @@ class VaultClient:
 
 **Token Expiry Timeline**:
 
-```
+```text
 Time:     0min        55min        60min        24hr         7d
           |           |            |            |            |
 Access:   [========= JWT valid =========][expired]
@@ -2368,7 +2368,7 @@ This method provides the best user experience for interactive CLI usage by lever
 
 **Detailed Implementation**:
 
-**Step 1: CLI initiates auth flow**
+#### Step 1: CLI initiates auth flow
 
 ```bash
 inferadb login
@@ -2402,7 +2402,7 @@ open_browser(&auth_url);
 start_callback_server(callback_port).await;
 ```
 
-**Step 2: Dashboard authenticates user and redirects**
+#### Step 2: Dashboard authenticates user and redirects
 
 Dashboard UI (`https://app.inferadb.com/cli-login`):
 
@@ -2444,18 +2444,18 @@ Dashboard UI (`https://app.inferadb.com/cli-login`):
    - `expires_at` (5 minutes from now)
 4. Return authorization code to Dashboard
 
-**Step 3: Dashboard redirects to CLI callback**
+#### Step 3: Dashboard redirects to CLI callback
 
-```
+```http
 HTTP/1.1 302 Found
 Location: http://localhost:8432/callback?code=<authorization_code>&state=<state>
 ```
 
-**Step 4: CLI receives callback and exchanges code for token**
+#### Step 4: CLI receives callback and exchanges code for token
 
 CLI callback handler receives:
 
-```
+```http
 GET /callback?code=<authorization_code>&state=<state>
 ```
 
@@ -2491,15 +2491,15 @@ CLI calls Management API to exchange code for session token:
 4. Return the session token associated with the authorization code
 5. CLI stores session token in secure storage
 
-**Step 5: CLI uses session token for API requests**
+#### Step 5: CLI uses session token for API requests
 
 ```bash
 inferadb vaults list
 ```
 
 CLI includes session token in requests:
 
-```
+```http
 GET /v1/organizations
 Authorization: Bearer <session_token>
 ```
@@ -2611,7 +2611,7 @@ fn generate_client_assertion(client_id: &str, private_key_pem: &str) -> Result<S
 
 CLI/SDK exchanges client assertion for vault-scoped JWT:
 
-```
+```http
 POST /v1/token
 Content-Type: application/x-www-form-urlencoded
 
@@ -2682,7 +2682,7 @@ $ inferadb vaults list
 
 **Management API Request**:
 
-```
+```http
 GET /v1/organizations
 Authorization: Bearer <session_token>
 ```
@@ -3176,7 +3176,7 @@ pub struct SystemApiKey {
 
 ### JWT Client Assertion Flow
 
-**Step 1: Management API generates client assertion JWT**
+#### Step 1: Management API generates client assertion JWT
 
 When the Management API needs to call the Server API, it generates a short-lived JWT (client assertion) signed with its System API Key:
 
@@ -3223,7 +3223,7 @@ async fn generate_client_assertion(system_key: &SystemApiKey) -> Result<String>
 }
 ```
 
-**Step 2: Include JWT in gRPC metadata**
+#### Step 2: Include JWT in gRPC metadata
 
 ```rust
 use tonic::{metadata::MetadataValue, Request};
@@ -3252,7 +3252,7 @@ async fn create_server_client() -> Result<VaultManagementServiceClient<Channel>>
 }
 ```
 
-**Step 3: Server validates JWT using JWKS**
+#### Step 3: Server validates JWT using JWKS
 
 The Server API fetches the Management API's JWKS endpoint to retrieve public keys:
 
@@ -3514,7 +3514,7 @@ This section focuses on **tenant requests** and how the Server enforces VaultRol
 
 VaultRoles define what operations are permitted within a vault:
 
-```
+```text
 READER < WRITER < MANAGER < ADMIN
 ```
 
@@ -3705,7 +3705,7 @@ The Server API enforces tenant isolation by prefixing all storage operations wit
 
 **FoundationDB Keyspace** (Server side):
 
-```
+```text
 vault_<vault_id>/
   tuples/
     <namespace>/<object>/<relation>/<subject>
@@ -4504,7 +4504,7 @@ async fn main() -> Result<()> {
 
 All data is isolated by entity type and organization to ensure security:
 
-```
+```text
 mgmt/                                    # Namespace prefix
   users/
     <user_id>/                           # User data
diff --git a/loadtests/README.md b/loadtests/README.md
@@ -158,6 +158,7 @@ done
    ```
 
 2. Run tests against localhost:
+
    ```bash
    k6 run loadtests/auth.js
    ```
@@ -195,7 +196,7 @@ Each test defines custom metrics:
 
 ### Example Output
 
-```
+```text
 running (4m30.0s), 000/100 VUs, 12500 complete and 0 interrupted iterations
 default ✓ [======================================] 100 VUs  4m30s
 
