Skip to content

Commit b3b267c

Browse files
phauptphaupt
authored
Merge pull request #4 from MobileID-Strong-Authentication/docs/fix-reference-guide-typos
Docs/fix reference guide typos
2 parents f64bf87 + 5ac1add commit b3b267c

27 files changed

Lines changed: 550 additions & 209 deletions

‎.github/copilot-instructions.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Mobile ID Documentation - AI Agent Instructions
2+
3+
## Project Overview
4+
5+
This is a **VitePress-based technical documentation site** for Swisscom Mobile ID authentication services. The project documents two primary authentication methods:
6+
- **OIDC (OpenID Connect)** integration for modern web/mobile apps
7+
- **Legacy RESTful API** for direct Mobile ID integration
8+
9+
Key stakeholders: Application Providers (APs) integrating Mobile ID authentication into their applications.
10+
11+
## Architecture
12+
13+
### VitePress Structure
14+
- **Entry point**: [docs/index.md](docs/index.md) - home page with hero section and feature cards
15+
- **Configuration**: [docs/.vitepress/config.mts](docs/.vitepress/config.mts) - navigation, sidebars, theme, search
16+
- **Custom theme**: [docs/.vitepress/theme/](docs/.vitepress/theme/) - CSS overrides and theme customization
17+
- **Components**: [docs/components/](docs/components/) - Vue components (e.g., `CustomAPIComponent.vue` for OpenAPI rendering)
18+
19+
### Documentation Sections
20+
```
21+
/reference-guide/ - Legacy Mobile ID API (SOAP/REST, X.509 certs, SIM/App methods)
22+
/oidc/ - OpenID Connect integration guide (modern approach)
23+
/entraid/ - EntraID integration (work in progress)
24+
/rig-radius/ - RADIUS integration guide
25+
/api-reference/ - OpenAPI spec viewer (Swagger UI)
26+
/release-notes/ - Platform and client release notes
27+
```
28+
29+
### Key Technical Concepts
30+
- **Two authentication methods**: Mobile ID SIM (STK-based, SMS PDUs) and Mobile ID App (iOS/Android)
31+
- **OpenAPI spec**: [docs/public/openapi-mobileid.yaml](docs/public/openapi-mobileid.yaml) rendered via Swagger UI
32+
- **Static assets**: [docs/public/img/](docs/public/img/) for images, [docs/img/](docs/img/) for legacy paths
33+
34+
## Development Workflows
35+
36+
### Local Development
37+
```bash
38+
npm run docs:dev # Start dev server (default: http://localhost:5173)
39+
npm run docs:build # Build static site to docs/.vitepress/dist/
40+
npm run docs:preview # Preview production build
41+
```
42+
43+
### Build Output
44+
- Compiled site lives in `docs/.vitepress/dist/` (excluded from version control)
45+
- Cache at `docs/.vitepress/cache/` - can be safely deleted if build issues occur
46+
47+
## Content Conventions
48+
49+
### Markdown Patterns
50+
- **VitePress frontmatter**: Used for layout definitions (e.g., `layout: home` in [index.md](docs/index.md))
51+
- **Custom containers**: `::: info`, `::: warning`, `::: danger` for callouts
52+
- **Vue components**: Import and use inline (see [api-reference/api.md](docs/api-reference/api.md) for Swagger UI example)
53+
54+
### Technical Terminology
55+
Maintain consistency with Mobile ID nomenclature defined in [reference-guide/introduction.md](docs/reference-guide/introduction.md):
56+
- **AP** (Application Provider), **MSISDN**, **DTBD** (Data-To-Be-Displayed), **MSS** (Mobile Signature Service)
57+
- **RP** (Relying Party), **OP** (OpenID Provider) in OIDC context
58+
59+
### File Naming
60+
- Use kebab-case: `getting-started.md`, `cloud-integration-guide.md`
61+
- Avoid special characters except hyphens
62+
63+
## Navigation & Sidebar Management
64+
65+
Sidebar configuration in [config.mts](docs/.vitepress/config.mts) is section-specific:
66+
- Keys like `/reference-guide/` match URL paths
67+
- Items array defines order and visibility
68+
- Missing items won't appear in navigation even if file exists
69+
70+
When adding new pages:
71+
1. Create markdown file in appropriate section
72+
2. Add entry to corresponding sidebar in `config.mts`
73+
3. Consider adding to top-level nav if major section
74+
75+
## OpenAPI Integration
76+
77+
[CustomAPIComponent.vue](docs/components/CustomAPIComponent.vue) renders `openapi-mobileid.yaml` using Swagger UI:
78+
- Mounted client-side only (VitePress SSG requires `onMounted`)
79+
- Spec must be in `docs/public/` for build-time access
80+
- Update component imports in markdown files as `<script setup>` block
81+
82+
## Common Patterns
83+
84+
### Adding a New Documentation Page
85+
1. Create `.md` file in target section (e.g., `docs/oidc/new-topic.md`)
86+
2. Add frontmatter if needed (usually not required for regular pages)
87+
3. Update `docs/.vitepress/config.mts` sidebar for that section
88+
4. Link from related pages for discoverability
89+
90+
### Updating Configuration
91+
- **Theme colors/styles**: Edit `docs/.vitepress/theme/custom.css`
92+
- **Logo/favicon**: Replace files in `docs/public/` (referenced in `config.mts`)
93+
- **Search**: Local search is enabled by default in `config.mts`
94+
95+
### Handling Images
96+
- **Preferred path**: `/public/img/` → Reference as `/img/filename.png` in markdown
97+
- **Legacy path**: `/docs/img/` → Still works but avoid for new content
98+
- Always use absolute paths from site root: `/img/...` not `./img/...`
99+
100+
## Dependencies
101+
102+
- **vitepress@^1.6.4**: SSG framework (peer deps: Vue 3, Vite)
103+
- **swagger-ui**: OpenAPI spec rendering
104+
- No test framework configured (documentation-only project)
105+
106+
## Notes for AI Agents
107+
108+
- This is **documentation**, not application code - focus on content clarity and navigation flow
109+
- **No backend services** - purely static site generation
110+
- When suggesting structural changes, verify impact on [config.mts](docs/.vitepress/config.mts) navigation
111+
- OIDC section is the **current recommended approach** (reference-guide is legacy but still maintained)
112+
- Project is marked "Work in Progress" - expect frequent content updates

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Ignore temporary workspace directory
2+
tmp/
13
docs/.vitepress/dist
24
docs/.vitepress/cache
35
node_modules

‎docs/.vitepress/config.mts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,19 @@ import { defineConfig } from 'vitepress'
22

33
// https://vitepress.dev/reference/site-config
44
export default defineConfig({
5-
title: ' ',
5+
title: 'Mobile ID Documentation',
66
description: 'Technical documentation for Mobile ID integration',
77
base: '/',
88
lastUpdated: true,
9-
appearance: false,
9+
// Enable the built-in light/dark appearance switch in the navbar
10+
appearance: true,
1011

1112
head: [['link', { rel: 'icon', href: '/mobileid.svg' }]],
1213

1314
themeConfig: {
1415
// https://vitepress.dev/reference/default-theme-config
1516
logo: '/img/mobileid-colors.png',
17+
siteTitle: false, // Hide visual title, keep only logo (HTML <title> remains)
1618

1719
nav: [
1820
{ text: 'Home', link: '/' },

‎docs/.vitepress/theme/custom.css‎

Lines changed: 220 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,80 @@
33
--vp-c-brand-1: #4e5353;
44
--vp-c-brand-2: #029994; /* #009490 */
55
--vp-c-brand-3: #009490;
6-
--vp-font-family-base: 'Swisscom Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
7-
--vp-font-family-heading: 'Swisscom Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
6+
/* System fonts wie bei modernen Webseiten - ohne externe Font-Dateien */
7+
--vp-font-family-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;
8+
--vp-font-family-heading: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;
89

10+
/* Increase max width for better use of screen space */
11+
--vp-layout-max-width: 1600px;
12+
13+
/* Kleinere Schrift wie bei beem docs */
14+
font-size: 15px;
15+
line-height: 1.6;
16+
}
17+
18+
/* Leichtere Schrift für Body-Text - explizit 300 für dünnere Darstellung */
19+
body {
20+
font-weight: 300;
21+
}
22+
23+
/* Content-Bereich ebenfalls leichter */
24+
.vp-doc p,
25+
.vp-doc li,
26+
.vp-doc td {
27+
font-weight: 300;
28+
}
29+
30+
/* Headings etwas stärker für Kontrast */
31+
.vp-doc h1,
32+
.vp-doc h2,
33+
.vp-doc h3,
34+
.vp-doc h4 {
35+
font-weight: 600;
36+
}
37+
38+
/* Reduziere oberen Abstand */
39+
@media (min-width: 960px) {
40+
.VPDoc {
41+
padding-top: 24px !important;
42+
}
43+
}
44+
45+
/* Make content container wider */
46+
.VPDoc.has-aside .content-container {
47+
max-width: 100% !important;
48+
}
49+
50+
.vp-doc {
51+
max-width: 1200px !important;
52+
}
53+
54+
/* Improve table responsiveness */
55+
.vp-doc table {
56+
display: block;
57+
overflow-x: auto;
58+
max-width: 100%;
59+
margin: 1em 0;
960
}
1061

62+
.vp-doc table th,
63+
.vp-doc table td {
64+
white-space: normal;
65+
word-wrap: break-word;
66+
min-width: 100px;
67+
}
68+
69+
/* Dark mode: use VitePress defaults (close to beem) */
1170
.dark {
12-
--vp-c-bg: #515151;
13-
--vp-c-bg-alt: #515151;
14-
--vp-c-bg-elv: #515151;
15-
--vp-c-bg-soft: #515151;
71+
--vp-c-bg: #1b1b1f;
72+
--vp-c-bg-alt: #161618;
73+
--vp-c-bg-elv: #202127;
74+
--vp-c-bg-soft: #202127;
1675
}
1776

1877
/* Dark mode override #3a3a3a */
1978
html.dark img.feature-icon-info {
20-
content: url("/public/img/icon-info-light.svg");
79+
content: url("/img/icon-info-light.svg");
2180
}
2281

2382
html.dark img.feature-icon-security {
@@ -31,9 +90,162 @@ html.dark img.feature-icon-notes {
3190

3291
/* Or for more specific control */
3392
.VPContent.VPContent.is-home {
34-
background-image: url('/img/background-4.png');
93+
background-image: url('/img/background-home.jpg');
3594
background-size: cover;
3695
background-repeat: no-repeat;
3796
background-attachment: fixed; /* keep it fixed while scrolling */
3897
background-position: center center;
3998
}
99+
100+
/* beem-like: navbar readable over a photo background */
101+
.VPNavBar {
102+
background-color: rgba(255, 255, 255, 0.85) !important;
103+
box-shadow: 0 1px 4px rgba(0, 0, 0, 0.06);
104+
backdrop-filter: blur(6px);
105+
-webkit-backdrop-filter: blur(6px);
106+
}
107+
108+
html.dark .VPNavBar {
109+
background-color: rgba(26, 26, 26, 0.85) !important;
110+
box-shadow: 0 1px 4px rgba(255, 255, 255, 0.06);
111+
}
112+
113+
/* beem-like: home section spacing */
114+
.VPHome {
115+
min-height: 100vh;
116+
}
117+
118+
.VPHome,
119+
.VPHome .VPContent {
120+
padding-bottom: 0 !important;
121+
margin-bottom: 0 !important;
122+
}
123+
124+
/* beem-like: improve home hero readability */
125+
.VPHome .tagline {
126+
color: rgba(255, 255, 255, 0.92);
127+
text-shadow: 0 2px 14px rgba(0, 0, 0, 0.35);
128+
}
129+
130+
.VPHome .name,
131+
.VPHome .text {
132+
color: rgba(255, 255, 255, 0.98);
133+
text-shadow: 0 2px 18px rgba(0, 0, 0, 0.35);
134+
}
135+
136+
/* beem-like: consistent rounding */
137+
.VPButton,
138+
.VPFeature {
139+
border-radius: 8px !important;
140+
}
141+
142+
/* Frosted-glass callouts on the home page (beem-like readability) */
143+
.VPContent.is-home .vp-doc .custom-block {
144+
background-color: rgba(255, 255, 255, 0.72);
145+
border: 1px solid rgba(255, 255, 255, 0.35);
146+
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.12);
147+
backdrop-filter: blur(10px);
148+
-webkit-backdrop-filter: blur(10px);
149+
}
150+
151+
html.dark .VPContent.is-home .vp-doc .custom-block {
152+
background-color: rgba(18, 18, 18, 0.55);
153+
border-color: rgba(255, 255, 255, 0.10);
154+
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.45);
155+
}
156+
157+
/* beem-like WIP banner (custom HTML block) */
158+
.VPContent.is-home .wip-banner {
159+
margin: 2rem auto;
160+
padding: 1rem 1.5rem;
161+
border-radius: 6px;
162+
line-height: 1.6;
163+
164+
/* frosted glass (similar to beem docs) */
165+
background-color: rgba(255, 255, 255, 0.58);
166+
box-shadow: 0 1px 4px rgba(0, 0, 0, 0.06);
167+
backdrop-filter: blur(4px);
168+
-webkit-backdrop-filter: blur(4px);
169+
170+
border-left: 4px solid var(--vp-c-brand-2);
171+
color: rgba(17, 17, 19, 0.88);
172+
font-size: 0.95rem;
173+
box-sizing: border-box;
174+
max-width: var(--vp-layout-max-width);
175+
padding-left: calc(var(--vp-layout-max-width) / 20);
176+
padding-right: calc(var(--vp-layout-max-width) / 20);
177+
}
178+
179+
html.dark .VPContent.is-home .wip-banner {
180+
background-color: rgba(31, 31, 31, 0.62);
181+
color: #eee;
182+
}
183+
184+
/* beem-like: appearance toggle styling */
185+
:root {
186+
--mid-switch-border: rgba(60, 60, 67, 0.18);
187+
--mid-switch-bg: rgba(255, 255, 255, 0.55);
188+
--mid-switch-bg-hover: rgba(255, 255, 255, 0.70);
189+
--mid-switch-shadow: 0 1px 4px rgba(0, 0, 0, 0.06);
190+
}
191+
192+
html.dark {
193+
--mid-switch-border: rgba(255, 255, 255, 0.14);
194+
--mid-switch-bg: rgba(31, 31, 31, 0.55);
195+
--mid-switch-bg-hover: rgba(31, 31, 31, 0.70);
196+
--mid-switch-shadow: 0 1px 4px rgba(255, 255, 255, 0.06);
197+
}
198+
199+
/* VitePress default switch: `.VPSwitch` + `.check` */
200+
.VPSwitchAppearance {
201+
border-color: var(--mid-switch-border) !important;
202+
background-color: var(--mid-switch-bg) !important;
203+
box-shadow: var(--mid-switch-shadow);
204+
backdrop-filter: blur(6px);
205+
-webkit-backdrop-filter: blur(6px);
206+
}
207+
208+
.VPSwitchAppearance:hover {
209+
background-color: var(--mid-switch-bg-hover) !important;
210+
border-color: var(--vp-c-brand-1) !important;
211+
}
212+
213+
.VPSwitchAppearance .check {
214+
box-shadow: 0 2px 10px rgba(0, 0, 0, 0.10);
215+
}
216+
217+
html.dark .VPSwitchAppearance .check {
218+
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.45);
219+
}
220+
221+
/* Fix: keep sidebar width constant across desktop breakpoints.
222+
VitePress widens/narrows sidebar/title at >=1440px using a calc() that can
223+
shrink when --vp-layout-max-width is larger than the viewport (e.g. 1600px).
224+
*/
225+
@media (min-width: 1440px) {
226+
.VPSidebar.VPSidebar {
227+
width: var(--vp-sidebar-width) !important;
228+
max-width: var(--vp-sidebar-width) !important;
229+
padding-left: 32px !important;
230+
}
231+
232+
.VPNavBar.has-sidebar .title.title {
233+
width: var(--vp-sidebar-width) !important;
234+
padding-left: 32px !important;
235+
}
236+
237+
.VPNavBar.has-sidebar .content.content {
238+
padding-left: var(--vp-sidebar-width) !important;
239+
padding-right: 32px !important;
240+
}
241+
}
242+
243+
/* beem-like: smoother icons */
244+
.VPSwitchAppearance .icon [class^='vpi-'] {
245+
transition: opacity 0.18s ease, color 0.18s ease;
246+
color: rgba(60, 60, 67, 0.68);
247+
}
248+
249+
html.dark .VPSwitchAppearance .icon [class^='vpi-'] {
250+
color: rgba(223, 223, 214, 0.85);
251+
}

0 commit comments

Comments
 (0)