Skip to content

Commit c363002

Browse files
jnbdzclaude
jnbdz
and
claude
committed
Add MkDocs site for VDP documentation
Includes site configuration, GitHub Pages deploy workflow, docs content, and build tooling. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent e8c927a commit c363002

13 files changed

Lines changed: 1468 additions & 0 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
deploy:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- name: Setup Python
18+
uses: actions/setup-python@v5
19+
with:
20+
python-version: '3.x'
21+
22+
- name: Cache pip dependencies
23+
uses: actions/cache@v4
24+
with:
25+
path: ~/.cache/pip
26+
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
27+
restore-keys: |
28+
${{ runner.os }}-pip-
29+
30+
- name: Install dependencies
31+
run: pip install -r requirements.txt
32+
33+
- name: Build site
34+
run: mkdocs build --strict
35+
36+
- name: Copy CNAME to build output
37+
run: cp CNAME site/CNAME
38+
39+
- name: Deploy to GitHub Pages
40+
uses: peaceiris/actions-gh-pages@v4
41+
with:
42+
github_token: ${{ secrets.GITHUB_TOKEN }}
43+
publish_dir: ./site

‎CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
viewdescriptorprotocol.org

‎Makefile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
SHELL := /usr/bin/env bash
2+
3+
start: ## Start mkdocs server
4+
@if [[ -f ".venv/bin/activate" && -x ".venv/bin/python" ]]; then \
5+
echo "Using virtualenv Python"; \
6+
. .venv/bin/activate; \
7+
python -m mkdocs serve; \
8+
else \
9+
echo "Virtualenv not found. Using system Python"; \
10+
python -m mkdocs serve; \
11+
fi
12+
13+
build: ## Build mkdocs site
14+
@if [[ -f ".venv/bin/activate" && -x ".venv/bin/python" ]]; then \
15+
. .venv/bin/activate; \
16+
python -m mkdocs build; \
17+
else \
18+
python -m mkdocs build; \
19+
fi
20+
21+
help: ## Help
22+
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sed 's/Makefile://' | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-18s\033[0m %s\n", $$1, $$2}'

‎docs/assets/extra.css‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
/* VDP Brand Colors */
2+
:root {
3+
--md-primary-fg-color: #0f2137;
4+
--md-primary-fg-color--light: #1a3a5c;
5+
--md-primary-fg-color--dark: #0a1628;
6+
--md-accent-fg-color: #42a5f5;
7+
}
8+
9+
[data-md-color-scheme="slate"] {
10+
--md-primary-fg-color: #0f2137;
11+
--md-primary-fg-color--light: #1a3a5c;
12+
--md-primary-fg-color--dark: #0a1628;
13+
}
14+
15+
/* Hero section on landing page */
16+
.md-typeset .vdp-hero {
17+
text-align: center;
18+
padding: 2rem 1rem;
19+
}
20+
21+
.md-typeset .vdp-hero img {
22+
max-width: 180px;
23+
margin-bottom: 1rem;
24+
}
25+
26+
.md-typeset .vdp-hero h1 {
27+
font-size: 2.4rem;
28+
margin-bottom: 0.5rem;
29+
}
30+
31+
.md-typeset .vdp-hero .vdp-tagline {
32+
font-size: 1.25rem;
33+
opacity: 0.8;
34+
margin-bottom: 2rem;
35+
}
36+
37+
/* Feature grid */
38+
.md-typeset .vdp-features {
39+
display: grid;
40+
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
41+
gap: 1.5rem;
42+
margin: 2rem 0;
43+
}
44+
45+
.md-typeset .vdp-feature {
46+
padding: 1.5rem;
47+
border: 1px solid var(--md-default-fg-color--lightest);
48+
border-radius: 0.5rem;
49+
}
50+
51+
.md-typeset .vdp-feature h3 {
52+
margin-top: 0;
53+
}
54+
55+
/* Quick links */
56+
.md-typeset .vdp-links {
57+
display: flex;
58+
gap: 1rem;
59+
justify-content: center;
60+
flex-wrap: wrap;
61+
margin: 2rem 0;
62+
}
63+
64+
.md-typeset .vdp-links a {
65+
display: inline-block;
66+
padding: 0.75rem 1.5rem;
67+
border-radius: 0.25rem;
68+
font-weight: 600;
69+
text-decoration: none;
70+
}
71+
72+
.md-typeset .vdp-links a.primary {
73+
background: var(--md-primary-fg-color);
74+
color: white;
75+
}
76+
77+
.md-typeset .vdp-links a.secondary {
78+
border: 2px solid var(--md-primary-fg-color);
79+
color: var(--md-primary-fg-color);
80+
}
81+
82+
[data-md-color-scheme="slate"] .md-typeset .vdp-links a.secondary {
83+
border-color: var(--md-accent-fg-color);
84+
color: var(--md-accent-fg-color);
85+
}

‎docs/assets/logo.png‎

58 KB
Loading

‎docs/examples.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Examples
2+
3+
These are the canonical VDP examples. Each validates against the [VDP v0.1 schema](schema.md).
4+
5+
## Simple View Descriptor
6+
7+
The simplest possible view descriptor: a single template with no slots.
8+
9+
**Use case:** A login form, a static page, or any endpoint that maps to a single template.
10+
11+
```json title="vdp-simple.json"
12+
{
13+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/forms/form.html"
14+
}
15+
```
16+
17+
The server might deliver this via the `View-Template` HTTP header:
18+
19+
```http
20+
HTTP/1.1 200 OK
21+
Content-Type: application/json
22+
View-Template: https://github.com/SiteNetSoft/quarkus-pha/templates/components/forms/form.html
23+
24+
{"csrfToken": "abc123", "loginUrl": "/auth/login"}
25+
```
26+
27+
---
28+
29+
## Composed View Descriptor
30+
31+
A layout template with nested slots, forming a template tree. The sidebar layout has two slots: `sidebarNav` for navigation, and `mainContent` for a dashboard that itself contains three further slots.
32+
33+
**Use case:** A dashboard page with a sidebar navigation, stats cards, an activity table, and a chart.
34+
35+
```json title="vdp-composed.json"
36+
{
37+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/layouts/sidebar.html",
38+
"slots": {
39+
"sidebarNav": {
40+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/navigation/nav.html"
41+
},
42+
"mainContent": {
43+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/demos/dashboard.html",
44+
"slots": {
45+
"statsCards": {
46+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/card.html"
47+
},
48+
"activityTable": {
49+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/table.html"
50+
},
51+
"revenueChart": {
52+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/charts/chart.html"
53+
}
54+
}
55+
}
56+
}
57+
}
58+
```
59+
60+
The resulting template tree:
61+
62+
```
63+
sidebar.html
64+
├── sidebarNav → nav.html
65+
└── mainContent → dashboard.html
66+
├── statsCards → card.html
67+
├── activityTable → table.html
68+
└── revenueChart → chart.html
69+
```
70+
71+
This descriptor would typically be served as a standalone resource referenced via `Link` header:
72+
73+
```http
74+
Link: <https://example.com/views/dashboard.json>; rel="view-descriptor"
75+
```
76+
77+
---
78+
79+
## Multi-View Descriptor
80+
81+
Multiple named views for the same API response. The client selects a view based on context (device class, user preference, layout mode).
82+
83+
**Use case:** A product page with a full detail view and a compact card view.
84+
85+
```json title="vdp-multi-view.json"
86+
{
87+
"views": {
88+
"default": {
89+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/demos/dashboard.html",
90+
"slots": {
91+
"statsCards": {
92+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/card.html"
93+
},
94+
"activityTable": {
95+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/table.html"
96+
}
97+
}
98+
},
99+
"compact": {
100+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/card.html"
101+
}
102+
}
103+
}
104+
```
105+
106+
Clients SHOULD use the `default` view when no specific view is requested. When embedded inline, use the `_views` key:
107+
108+
```json
109+
{
110+
"_views": {
111+
"default": { "..." : "..." },
112+
"compact": { "..." : "..." }
113+
},
114+
"revenue": 48200,
115+
"users": 1847
116+
}
117+
```
118+
119+
---
120+
121+
## Slot Array
122+
123+
A single slot accepting multiple templates rendered in sequence. Each element is a full view descriptor.
124+
125+
**Use case:** A main content area that renders a card, chart, and table in order.
126+
127+
```json title="vdp-slot-array.json"
128+
{
129+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/layouts/sidebar.html",
130+
"slots": {
131+
"mainContent": [
132+
{
133+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/card.html"
134+
},
135+
{
136+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/charts/chart.html"
137+
},
138+
{
139+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/data-display/table.html"
140+
}
141+
],
142+
"sidebarNav": {
143+
"template": "https://github.com/SiteNetSoft/quarkus-pha/templates/components/navigation/nav.html"
144+
}
145+
}
146+
}
147+
```
148+
149+
The `mainContent` slot receives an array of three view descriptors. The client MUST render them in order:
150+
151+
1. `card.html`
152+
2. `chart.html`
153+
3. `table.html`
154+
155+
Each array element can itself contain nested `slots` for further composition.

0 commit comments

Comments
 (0)