Skip to content

Commit 022b20c

Browse files
jhagbergjwindhager
jhagberg
and
jwindhager
authored
ADR-004 Add MkDocs Material Documentation Site (#6)
* Update README to correct formatting and enhance clarity of technical architecture governance description * Add decision document for using MkDocs Material as the documentation site * Add MkDocs configuration, deploy workflow, and initial documentation files - MkDocs Material theme with SciLifeLab visual identity - GitHub Actions workflow for automatic deployment - Homepage with mission, workflow diagram, and board members - Custom CSS for teal/lime branding - Cookie consent and Mermaid diagram support * Apply suggestions from code review Co-authored-by: Jonas Windhager <jonas@windhager.io> * Update documentation diagrams and styles for improved clarity and branding - Enhanced Mermaid diagrams with a unified theme for consistency across documentation. - Updated CSS for primary and secondary button styles to align with the new color scheme. * Add requirements file and update deployment workflow - Introduced a requirements.txt file to manage dependencies, specifically for mkdocs-material. - Updated the GitHub Actions workflow to install dependencies from requirements.txt instead of directly installing mkdocs-material. * Update response time language in architecture help section for clarity * Update GitHub link in MkDocs configuration and improve Git credentials formatting in deployment workflow * Update title of decision document to include ADR prefix for consistency * Update documentation to reflect broader academic community engagement in Architecture Board contributions --------- Co-authored-by: Jonas Windhager <jonas@windhager.io>
1 parent ef8c692 commit 022b20c

12 files changed

Lines changed: 443 additions & 4 deletions

‎.github/pull_request_template.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Description
2+
3+
Brief description of changes.
4+
5+
## Type of Change
6+
7+
- [ ] Bug fix
8+
- [ ] New feature
9+
- [ ] Documentation update
10+
- [ ] ADR (Architecture Decision Record)
11+
12+
## ADR Checklist (if applicable)
13+
14+
If this PR includes a new ADR, ensure:
15+
16+
- [ ] ADR is added to `mkdocs.yml` nav section
17+
- [ ] ADR is added to "Recent Decisions" table in `docs/index.md`
18+
- [ ] ADR follows the standard template
19+
20+
## Review
21+
22+
- [ ] I have reviewed my own changes
23+
- [ ] Documentation is updated (if needed)
24+

‎.github/workflows/deploy-docs.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: write
12+
13+
jobs:
14+
deploy:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v6
18+
with:
19+
fetch-depth: 0
20+
21+
- name: Configure Git Credentials
22+
run: |
23+
git config user.name "github-actions[bot]"
24+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
25+
26+
- uses: actions/setup-python@v6
27+
with:
28+
python-version: 3.x
29+
30+
- name: Cache dependencies
31+
uses: actions/cache@v4
32+
with:
33+
key: mkdocs-material-${{ github.ref }}
34+
path: ~/.cache
35+
restore-keys: |
36+
mkdocs-material-
37+
38+
- name: Install dependencies
39+
run: pip install -r requirements.txt
40+
41+
- name: Build and Deploy
42+
run: mkdocs gh-deploy --force

‎docs/assets/favicon.png‎

76.3 KB
Loading

‎docs/assets/logo.png‎

76.3 KB
Loading

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

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,12 @@ Use a **single unified process** where formality emerges naturally from impact.
2424
**Process:**
2525

2626
```mermaid
27+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#a7c947', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#8bb030', 'lineColor': '#045c64', 'secondaryColor': '#e8f5e9', 'tertiaryColor': '#f5f5f5', 'fontFamily': 'Open Sans'}}}%%
2728
flowchart LR
2829
A[Open Issue] --> B{Discussion<br/>Time varies}
2930
B -->|Simple| C[Close with<br/>Answer]
3031
B -->|Complex| D[Create ADR PR]
3132
D --> E[Publish]
32-
33-
style A fill:#e1f5ff
34-
style D fill:#fff4e1
35-
style E fill:#e8f5e9
3633
```
3734

3835
**Key insight:** Same process, different discussion length based on natural impact.

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

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# ADR-0004. Use MkDocs Material for Documentation Site
2+
3+
Date: 2025-11-28
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
We need a documentation site to publish ADRs, standards, and process documentation at `https://scilifelab.github.io/architecture/`.
12+
13+
Requirements:
14+
15+
- Automatic publishing from GitHub
16+
- Support for Mermaid diagrams (same syntax as GitHub)
17+
- Search functionality
18+
- Easy for contributors (just Markdown)
19+
- Professional appearance
20+
- Adaptable to SciLifeLab visual identity
21+
22+
## Decision
23+
24+
Use **MkDocs Material** with SciLifeLab visual customization.
25+
26+
## Rationale
27+
28+
**Simple and effective:**
29+
30+
- Markdown → beautiful website in 5 minutes
31+
- Built-in Mermaid support (identical to GitHub)
32+
- Contributors only need Markdown knowledge
33+
- Industry standard (Google, Microsoft use it)
34+
35+
**Better than alternatives:**
36+
37+
- Quarto: Too complex for pure documentation
38+
- Jekyll: Less modern, more configuration
39+
- Custom solution: Unnecessary maintenance burden
40+
41+
**Customizable:**
42+
Material theme easily adapted to SciLifeLab brand through `mkdocs.yml` configuration.
43+
44+
## Consequences
45+
46+
**Positive:**
47+
48+
- Fast deployment
49+
- Low contributor barrier
50+
- Professional appearance
51+
- Excellent search
52+
- Automatic publishing via GitHub Actions
53+
54+
**Negative:**
55+
56+
- Web-only output (no native PDF)
57+
- Brand customization limited to theme capabilities
58+
59+
**Implementation:**
60+
Create `mkdocs.yml` with Material theme, SciLifeLab colors, and GitHub Actions deployment.

‎docs/decisions/templates/template.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ The change that we're proposing or have agreed to implement.
1717
## Consequences
1818

1919
What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.
20+

‎docs/index.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# SciLifeLab Architecture Board
2+
3+
> Ensuring interoperable, sustainable, and FAIR infrastructure across SciLifeLab's federated platforms.
4+
5+
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.
6+
7+
!!! question "Need Architecture Help?"
8+
9+
- No question too small
10+
- We aim to respond promptly
11+
- Early guidance prevents expensive mistakes
12+
13+
[:octicons-issue-opened-16: Open an Issue](https://github.com/SciLifeLab/architecture/issues/new?template=architecture-question.md){ .md-button .md-button--primary }
14+
[:octicons-comment-discussion-16: Start a Discussion](https://github.com/SciLifeLab/architecture/discussions){ .md-button }
15+
[:octicons-mail-16: architecture@scilifelab.se](mailto:architecture@scilifelab.se){ .md-button }
16+
17+
## What We Do
18+
19+
```mermaid
20+
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#a7c947', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#8bb030', 'lineColor': '#045c64', 'secondaryColor': '#e8f5e9', 'tertiaryColor': '#f5f5f5', 'fontFamily': 'Open Sans'}}}%%
21+
graph LR
22+
A[Project Team] -->|Question| B[Architecture Board]
23+
B -->|Guidance| A
24+
B -->|Decision| C[ADR]
25+
C -->|Published| D[Documentation]
26+
D -->|Informs| A
27+
```
28+
29+
### :material-compass: Architecture Guidance
30+
31+
Best practices for technical design, integration patterns, and technology choices.
32+
33+
### :material-file-document-edit: Decision Records
34+
35+
Transparent documentation of all significant architectural decisions (ADRs).
36+
37+
### :material-connection: Cross-Platform Coordination
38+
39+
Facilitate collaboration to ensure coherent architecture across SciLifeLab.
40+
41+
## Recent Decisions
42+
43+
| Decision | Status | Summary |
44+
| --------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
45+
| [ADR-0004: MkDocs Material](decisions/0004-use-mkdocs-material-for-documentation-site.md) | Accepted | Use MkDocs Material for documentation site |
46+
| [ADR-0003: Single Process](decisions/0003-use-single-process-approach-for-architecture-requests.md) | Accepted | Single process for architecture requests |
47+
| [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 |
48+
| [ADR-0001: Record Decisions](decisions/0001-record-architecture-decisions.md) | Accepted | Record architecture decisions as ADRs |
49+
50+
## Board Members
51+
52+
| Name | Affiliation | Role |
53+
| ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
54+
| Jonas Hagberg | NBIS | Chair, [Certified IT Architect](https://app.diplomasafe.com/sv-SE/diploma/d2e66e08f42702140adfb61a0fb2315ef6d93ccb8) |
55+
| Johan Viklund | NBIS | Technical Expert |
56+
| Jonas Söderberg | NBIS SCoRe | Technical Expert |
57+
| Johannes Alneberg | NGI | Technical Expert |
58+
| Jonas Windhager | NBIS BIIF | Technical Expert |
59+
60+
_Adjunct members: Björn Nystedt, Hanna Kultima (Integrated Data Services Project Management Team)_
61+
62+
## Get Involved
63+
64+
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.
65+
66+
!!! tip "How to Contribute"
67+
68+
1. **Not sure yet?** Start a [GitHub Discussion](https://github.com/SciLifeLab//architecture/discussions) or email [architecture@scilifelab.se](mailto:architecture@scilifelab.se)
69+
2. **Have a question?** Open a [GitHub Issue](https://github.com/SciLifeLab/architecture/issues) to get guidance
70+
3. **Proposing a change?** Create an ADR following our [template](decisions/0001-record-architecture-decisions.md)
71+
4. **Found an issue?** Submit a pull request with your suggested improvements
72+
73+
---
74+
75+
Part of [SciLifeLab](https://scilifelab.se) – Sweden's national infrastructure for life sciences research.
76+
77+
**Please cite as:**
78+
SciLifeLab Architecture Board. (2025). _SciLifeLab Architecture Governance._ GitHub repository: <https://github.com/SciLifeLab/architecture>

‎docs/stylesheets/extra.css‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
/* SciLifeLab Visual Identity Colors */
2+
3+
@import url("https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700&display=swap");
4+
5+
:root {
6+
/* SciLifeLab Brand Colors */
7+
--scilifelab-lime: #a7c947;
8+
--scilifelab-lime-dark: #8bb030;
9+
--scilifelab-teal: #045c64;
10+
--scilifelab-teal-dark: #034750;
11+
12+
/* MkDocs Material overrides */
13+
--md-primary-fg-color: #045c64;
14+
--md-primary-fg-color--light: #067a85;
15+
--md-primary-fg-color--dark: #034750;
16+
--md-accent-fg-color: #a7c947;
17+
18+
/* Typography */
19+
--md-text-font: "Open Sans", -apple-system, BlinkMacSystemFont, Helvetica,
20+
Arial, sans-serif;
21+
}
22+
23+
/* Dark mode */
24+
[data-md-color-scheme="slate"] {
25+
--md-primary-fg-color: #045c64;
26+
--md-accent-fg-color: #a7c947;
27+
--md-typeset-a-color: #a7c947;
28+
}
29+
30+
/* Header - Teal */
31+
.md-header {
32+
background-color: #045c64;
33+
}
34+
35+
/* Navigation tabs */
36+
.md-tabs {
37+
background-color: #034750;
38+
}
39+
40+
/* Logo sizing */
41+
.md-header__button.md-logo img {
42+
height: 1.6rem;
43+
width: auto;
44+
}
45+
46+
/* Links in content */
47+
.md-typeset a:not(.md-button) {
48+
color: #045c64;
49+
}
50+
51+
[data-md-color-scheme="slate"] .md-typeset a:not(.md-button) {
52+
color: #a7c947;
53+
}
54+
55+
/* Headings */
56+
.md-typeset h2 {
57+
border-bottom: 2px solid #a7c947;
58+
padding-bottom: 0.4rem;
59+
}
60+
61+
/* Tables */
62+
.md-typeset table:not([class]) th {
63+
background-color: #045c64;
64+
color: white;
65+
}
66+
67+
/* Code */
68+
.md-typeset code {
69+
background-color: rgba(4, 92, 100, 0.1);
70+
color: #045c64;
71+
}
72+
73+
[data-md-color-scheme="slate"] .md-typeset code {
74+
background-color: rgba(167, 201, 71, 0.15);
75+
color: #c5db7a;
76+
}
77+
78+
/* Buttons - Primary (lime) */
79+
.md-typeset .md-button--primary {
80+
background-color: #a7c947;
81+
border-color: #a7c947;
82+
color: #1a1a1a;
83+
}
84+
85+
.md-typeset .md-button--primary:hover {
86+
background-color: #8bb030;
87+
border-color: #8bb030;
88+
}
89+
90+
/* Buttons - Secondary in dark mode: Teal with white text */
91+
[data-md-color-scheme="slate"] .md-typeset .md-button:not(.md-button--primary) {
92+
background-color: #045c64;
93+
border-color: #045c64;
94+
color: #ffffff;
95+
}
96+
97+
[data-md-color-scheme="slate"]
98+
.md-typeset
99+
.md-button:not(.md-button--primary):hover {
100+
background-color: #067a85;
101+
border-color: #067a85;
102+
color: #ffffff;
103+
}
104+
105+
/* Footer */
106+
.md-footer {
107+
background-color: #045c64;
108+
}
109+
110+
.md-footer-meta {
111+
background-color: #034750;
112+
}
113+
114+
/* Admonitions */
115+
.md-typeset .admonition.note,
116+
.md-typeset details.note {
117+
border-color: #045c64;
118+
}
119+
120+
.md-typeset .admonition.tip,
121+
.md-typeset details.tip {
122+
border-color: #a7c947;
123+
}
124+
125+
/* Active nav item */
126+
.md-nav__link--active {
127+
color: #045c64 !important;
128+
}
129+
130+
[data-md-color-scheme="slate"] .md-nav__link--active {
131+
color: #a7c947 !important;
132+
}

0 commit comments

Comments
 (0)