ADR-004 Add MkDocs Material Documentation Site

.github/PULL_REQUEST_TEMPLATE/adr.md

@@ -0,0 +1,24 @@
+## ADR Pull Request
+
+### Description
+
+Brief description of the architectural decision.
+
+### Checklist
+
+Before merging, ensure the following are complete:
+
+- [ ] ADR document follows the [template](docs/decisions/0001-record-architecture-decisions.md)
+- [ ] ADR is added to `mkdocs.yml` navigation:
+  ```yaml
+  nav:
+    - Architecture Decisions:
+        - decisions/XXXX-your-adr-name.md  # Add here
+  ```
+- [ ] ADR is added to the "Recent Decisions" table in `docs/index.md`
+- [ ] ADR has been reviewed by at least one board member
+
+### Related Issues
+
+Closes #
+

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description
+
+Brief description of changes.
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] ADR (Architecture Decision Record)
+
+## ADR Checklist (if applicable)
+
+If this PR includes a new ADR, ensure:
+
+- [ ] ADR is added to `mkdocs.yml` nav section
+- [ ] ADR is added to "Recent Decisions" table in `docs/index.md`
+- [ ] ADR follows the standard template
+
+## Review
+
+- [ ] I have reviewed my own changes
+- [ ] Documentation is updated (if needed)
+

.github/workflows/deploy-docs.yml

@@ -0,0 +1,42 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ github.ref }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Build and Deploy
+        run: mkdocs gh-deploy --force

README.md

@@ -4,6 +4,8 @@
 
 Technical architecture governance for SciLifeLab infrastructure - ensuring interoperability, standards, and sustainable design
 
+Technical architecture governance for SciLifeLab infrastructure - ensuring interoperability, standards, and sustainable design
+
 This work is licensed under a
 [Creative Commons Attribution-ShareAlike 4.0 International License][cc-by-sa].
 

docs/decisions/0003-use-single-process-approach-for-architecture-requests.md

@@ -24,15 +24,12 @@ Use a **single unified process** where formality emerges naturally from impact.
 **Process:**
 
 ```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#a7c947', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#8bb030', 'lineColor': '#045c64', 'secondaryColor': '#e8f5e9', 'tertiaryColor': '#f5f5f5', 'fontFamily': 'Open Sans'}}}%%
 flowchart LR
     A[Open Issue] --> B{Discussion<br/>Time varies}
     B -->|Simple| C[Close with<br/>Answer]
     B -->|Complex| D[Create ADR PR]
     D --> E[Publish]
-
-    style A fill:#e1f5ff
-    style D fill:#fff4e1
-    style E fill:#e8f5e9
 ```
 
 **Key insight:** Same process, different discussion length based on natural impact.

docs/decisions/0004-use-mkdocs-material-for-documentation-site.md

@@ -0,0 +1,60 @@
+# ADR-0004. Use MkDocs Material for Documentation Site
+
+Date: 2025-11-28
+
+## Status
+
+Accepted
+
+## Context
+
+We need a documentation site to publish ADRs, standards, and process documentation at `https://scilifelab.github.io/architecture/`.
+
+Requirements:
+
+- Automatic publishing from GitHub
+- Support for Mermaid diagrams (same syntax as GitHub)
+- Search functionality
+- Easy for contributors (just Markdown)
+- Professional appearance
+- Adaptable to SciLifeLab visual identity
+
+## Decision
+
+Use **MkDocs Material** with SciLifeLab visual customization.
+
+## Rationale
+
+**Simple and effective:**
+
+- Markdown → beautiful website in 5 minutes
+- Built-in Mermaid support (identical to GitHub)
+- Contributors only need Markdown knowledge
+- Industry standard (Google, Microsoft use it)
+
+**Better than alternatives:**
+
+- Quarto: Too complex for pure documentation
+- Jekyll: Less modern, more configuration
+- Custom solution: Unnecessary maintenance burden
+
+**Customizable:**
+Material theme easily adapted to SciLifeLab brand through `mkdocs.yml` configuration.
+
+## Consequences
+
+**Positive:**
+
+- Fast deployment
+- Low contributor barrier
+- Professional appearance
+- Excellent search
+- Automatic publishing via GitHub Actions
+
+**Negative:**
+
+- Web-only output (no native PDF)
+- Brand customization limited to theme capabilities
+
+**Implementation:**
+Create `mkdocs.yml` with Material theme, SciLifeLab colors, and GitHub Actions deployment.

docs/index.md

@@ -0,0 +1,78 @@
+# SciLifeLab Architecture Board
+
+> Ensuring interoperable, sustainable, and FAIR infrastructure across SciLifeLab's federated platforms.
+
+The Architecture Board provides technical governance and guidance for SciLifeLab infrastructure, enabling seamless collaboration while respecting platform autonomy. We support decision-making for technical architecture across all SciLifeLab platforms and services.
+
+!!! question "Need Architecture Help?"
+
+    - No question too small
+    - We aim to respond promptly
+    - Early guidance prevents expensive mistakes
+
+    [:octicons-issue-opened-16: Open an Issue](https://github.com/SciLifeLab/architecture/issues/new?template=architecture-question.md){ .md-button .md-button--primary }
+    [:octicons-comment-discussion-16: Start a Discussion](https://github.com/SciLifeLab/architecture/discussions){ .md-button }
+    [:octicons-mail-16: architecture@scilifelab.se](mailto:architecture@scilifelab.se){ .md-button }
+
+## What We Do
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#a7c947', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#8bb030', 'lineColor': '#045c64', 'secondaryColor': '#e8f5e9', 'tertiaryColor': '#f5f5f5', 'fontFamily': 'Open Sans'}}}%%
+graph LR
+    A[Project Team] -->|Question| B[Architecture Board]
+    B -->|Guidance| A
+    B -->|Decision| C[ADR]
+    C -->|Published| D[Documentation]
+    D -->|Informs| A
+```
+
+### :material-compass: Architecture Guidance
+
+Best practices for technical design, integration patterns, and technology choices.
+
+### :material-file-document-edit: Decision Records
+
+Transparent documentation of all significant architectural decisions (ADRs).
+
+### :material-connection: Cross-Platform Coordination
+
+Facilitate collaboration to ensure coherent architecture across SciLifeLab.
+
+## Recent Decisions
+
+| Decision                                                                                            | Status   | Summary                                    |
+| --------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
+| [ADR-0004: MkDocs Material](decisions/0004-use-mkdocs-material-for-documentation-site.md)           | Accepted | Use MkDocs Material for documentation site |
+| [ADR-0003: Single Process](decisions/0003-use-single-process-approach-for-architecture-requests.md) | Accepted | Single process for architecture requests   |
+| [ADR-0002: CC BY-SA 4.0](decisions/0002-use-cc-by-sa-4-0-license.md)                                | Accepted | Use CC BY-SA 4.0 license for content       |
+| [ADR-0001: Record Decisions](decisions/0001-record-architecture-decisions.md)                       | Accepted | Record architecture decisions as ADRs      |
+
+## Board Members
+
+| Name              | Affiliation | Role                                                                                                                 |
+| ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| Jonas Hagberg     | NBIS        | Chair, [Certified IT Architect](https://app.diplomasafe.com/sv-SE/diploma/d2e66e08f42702140adfb61a0fb2315ef6d93ccb8) |
+| Johan Viklund     | NBIS        | Technical Expert                                                                                                     |
+| Jonas Söderberg   | NBIS SCoRe  | Technical Expert                                                                                                     |
+| Johannes Alneberg | NGI         | Technical Expert                                                                                                     |
+| Jonas Windhager   | NBIS BIIF   | Technical Expert                                                                                                     |
+
+_Adjunct members: Björn Nystedt, Hanna Kultima (Integrated Data Services Project Management Team)_
+
+## Get Involved
+
+The Architecture Board welcomes input from all SciLifeLab teams and the broader academic community. Whether you have a technical proposal, an architecture concern, or need guidance on a decision, we're here to help.
+
+!!! tip "How to Contribute"
+
+    1. **Not sure yet?** Start a [GitHub Discussion](https://github.com/SciLifeLab//architecture/discussions) or email [architecture@scilifelab.se](mailto:architecture@scilifelab.se)
+    2. **Have a question?** Open a [GitHub Issue](https://github.com/SciLifeLab/architecture/issues) to get guidance
+    3. **Proposing a change?** Create an ADR following our [template](decisions/0001-record-architecture-decisions.md)
+    4. **Found an issue?** Submit a pull request with your suggested improvements
+
+---
+
+Part of [SciLifeLab](https://scilifelab.se) – Sweden's national infrastructure for life sciences research.
+
+**Please cite as:**
+SciLifeLab Architecture Board. (2025). _SciLifeLab Architecture Governance._ GitHub repository: <https://github.com/SciLifeLab/architecture>

docs/stylesheets/extra.css

@@ -0,0 +1,132 @@
+/* SciLifeLab Visual Identity Colors */
+
+@import url("https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700&display=swap");
+
+:root {
+  /* SciLifeLab Brand Colors */
+  --scilifelab-lime: #a7c947;
+  --scilifelab-lime-dark: #8bb030;
+  --scilifelab-teal: #045c64;
+  --scilifelab-teal-dark: #034750;
+
+  /* MkDocs Material overrides */
+  --md-primary-fg-color: #045c64;
+  --md-primary-fg-color--light: #067a85;
+  --md-primary-fg-color--dark: #034750;
+  --md-accent-fg-color: #a7c947;
+
+  /* Typography */
+  --md-text-font: "Open Sans", -apple-system, BlinkMacSystemFont, Helvetica,
+    Arial, sans-serif;
+}
+
+/* Dark mode */
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #045c64;
+  --md-accent-fg-color: #a7c947;
+  --md-typeset-a-color: #a7c947;
+}
+
+/* Header - Teal */
+.md-header {
+  background-color: #045c64;
+}
+
+/* Navigation tabs */
+.md-tabs {
+  background-color: #034750;
+}
+
+/* Logo sizing */
+.md-header__button.md-logo img {
+  height: 1.6rem;
+  width: auto;
+}
+
+/* Links in content */
+.md-typeset a:not(.md-button) {
+  color: #045c64;
+}
+
+[data-md-color-scheme="slate"] .md-typeset a:not(.md-button) {
+  color: #a7c947;
+}
+
+/* Headings */
+.md-typeset h2 {
+  border-bottom: 2px solid #a7c947;
+  padding-bottom: 0.4rem;
+}
+
+/* Tables */
+.md-typeset table:not([class]) th {
+  background-color: #045c64;
+  color: white;
+}
+
+/* Code */
+.md-typeset code {
+  background-color: rgba(4, 92, 100, 0.1);
+  color: #045c64;
+}
+
+[data-md-color-scheme="slate"] .md-typeset code {
+  background-color: rgba(167, 201, 71, 0.15);
+  color: #c5db7a;
+}
+
+/* Buttons - Primary (lime) */
+.md-typeset .md-button--primary {
+  background-color: #a7c947;
+  border-color: #a7c947;
+  color: #1a1a1a;
+}
+
+.md-typeset .md-button--primary:hover {
+  background-color: #8bb030;
+  border-color: #8bb030;
+}
+
+/* Buttons - Secondary in dark mode: Teal with white text */
+[data-md-color-scheme="slate"] .md-typeset .md-button:not(.md-button--primary) {
+  background-color: #045c64;
+  border-color: #045c64;
+  color: #ffffff;
+}
+
+[data-md-color-scheme="slate"]
+  .md-typeset
+  .md-button:not(.md-button--primary):hover {
+  background-color: #067a85;
+  border-color: #067a85;
+  color: #ffffff;
+}
+
+/* Footer */
+.md-footer {
+  background-color: #045c64;
+}
+
+.md-footer-meta {
+  background-color: #034750;
+}
+
+/* Admonitions */
+.md-typeset .admonition.note,
+.md-typeset details.note {
+  border-color: #045c64;
+}
+
+.md-typeset .admonition.tip,
+.md-typeset details.tip {
+  border-color: #a7c947;
+}
+
+/* Active nav item */
+.md-nav__link--active {
+  color: #045c64 !important;
+}
+
+[data-md-color-scheme="slate"] .md-nav__link--active {
+  color: #a7c947 !important;
+}