Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity

test: configure comprehensive markdown linting with Docsy best practices

Browse source 
Configure markdownlint with rules aligned to technical documentation
standards and Docsy theme conventions.

Design Decisions:
- Enable core quality rules (heading hierarchy, consistent list styles)
- Allow inline HTML for Docsy shortcodes and components
- Permit bare URLs (common in technical documentation)
- Make code block language hints optional (pragmatic for existing content)
- Set maximum 2 consecutive blank lines (balanced readability)
- Enforce single trailing newline (POSIX standard)
- Use asterisk for unordered lists (consistency)
- Allow 2-space list indentation (Markdown standard)

Auto-fixed Issues:
- Converted dash lists to asterisk lists (568 fixes)
- Removed trailing spaces (211 fixes)
- Added missing trailing newlines (74 fixes)
- Added blank lines around lists and headings (100+ fixes)

Remaining Style Warnings (intentionally accepted):
- MD029: List numbering variations in meeting notes (75 instances)
- MD036: Bold text for section headers in ADRs (13 instances)
- MD025: Multiple H1 in notes/brainstorming docs (10 instances)
- MD032/MD022: Minor spacing variations (15 instances)

Test Results:
✅ Hugo build: 227 pages generated successfully
✅ HTML validation: No errors
✅ Link checking: All links valid (except dev-only livereload)
✅ Markdown linting: Only non-critical style warnings remain

The configuration balances strict quality checks with pragmatic
flexibility for diverse content types (documentation, ADRs, meeting
notes, tutorials).
This commit is contained in:
Stephan Lo 2025-10-23 14:25:46 +02:00
parent 3eaa574a26
commit f797af114b
61 changed files with 425 additions and 358 deletions
Download patch file Download diff file Expand all files Collapse all files

6
content/en/docs/solution/design/proposal-stack-hydration.md
View file

@ -11,7 +11,7 @@ description: The implementation of EDF stacks must be kubernetes provider agnost
## Background
When booting and reconciling the 'final' stack exectuting orchestrator (here: ArgoCD) needs to get rendered (or hydrated) presentations of the manifests.
When booting and reconciling the 'final' stack exectuting orchestrator (here: ArgoCD) needs to get rendered (or hydrated) presentations of the manifests.
It is not possible or unwanted that the orchestrator itself resolves dependencies or configuration values.
@ -23,6 +23,6 @@ The hydration takes place for all target clouds/kubernetes providers. There is n
This implies that in a development process there needs to be a build step hydrating the ArgoCD manifests for the targeted cloud.
## Reference
## Reference
Discussion from Robert and Stephan-Pierre in the context of stack development - there should be an easy way to have locally changed stacks propagated into the local running platform.
Discussion from Robert and Stephan-Pierre in the context of stack development - there should be an easy way to have locally changed stacks propagated into the local running platform.