Skip to content

Commit 8599ced

Browse files
phauptphaupt
committed
docs: add SEO and indexing setup for search engines and AI agents
Previously missing: - No robots.txt → crawlers had no directives or sitemap reference - No sitemap.xml → search engines could not discover pages automatically - No llms.txt → AI agents had no structured entry point - No CNAME file → GitHub Pages custom domain not pinned in repo - No canonical URLs, OpenGraph, or robots meta tags on pages - lang attribute not set on <html> What's added: - robots.txt (Allow all, references sitemap) - Automatic sitemap.xml generation via VitePress built-in sitemap config - llms.txt with structured links to all documentation sections - CNAME for docs.mobileid.ch - Per-page canonical <link> and OpenGraph meta tags via transformPageData - Site-wide robots, og:site_name, og:type, twitter:card meta tags - lang: 'en' in VitePress config - Homepage title/description frontmatter for proper OG fallback - SEO documentation section in README
1 parent cc29a3a commit 8599ced

6 files changed

Lines changed: 135 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,51 @@
55
This repository contains documentation resources related to MobileID.
66

77
For full documentation, visit the official site:
8-
- [MobileID Documentation](https://docs.mobileid.ch)
8+
- [MobileID Documentation](https://docs.mobileid.ch)
9+
10+
## SEO & Indexing
11+
12+
The site is configured for search-engine and AI-agent discoverability. Everything is generated automatically during `npm run docs:build`.
13+
14+
### What's set up
15+
16+
| Artifact | Source | Deployed URL |
17+
|---|---|---|
18+
| `robots.txt` | `docs/public/robots.txt` (static) | https://docs.mobileid.ch/robots.txt |
19+
| `sitemap.xml` | Auto-generated by VitePress (`sitemap.hostname` in config) | https://docs.mobileid.ch/sitemap.xml |
20+
| `llms.txt` | `docs/public/llms.txt` (static) | https://docs.mobileid.ch/llms.txt |
21+
| `CNAME` | `docs/public/CNAME` (static) | — (consumed by GitHub Pages) |
22+
23+
### Meta tags (per page, automatic)
24+
25+
Every built page includes:
26+
- `<link rel="canonical">` pointing to `https://docs.mobileid.ch/…`
27+
- `<meta name="robots" content="index, follow">`
28+
- OpenGraph tags (`og:title`, `og:description`, `og:url`, `og:site_name`, `og:type`)
29+
- Twitter summary card
30+
31+
These are injected via `transformPageData` in `docs/.vitepress/config.mts`.
32+
33+
### How sitemap generation works
34+
35+
VitePress 1.x has built-in sitemap support. The config contains:
36+
37+
```ts
38+
sitemap: {
39+
hostname: 'https://docs.mobileid.ch',
40+
}
41+
```
42+
43+
On every build, VitePress generates `sitemap.xml` in the dist root with `<lastmod>` timestamps derived from git history (because `lastUpdated: true`).
44+
45+
### Maintaining `llms.txt`
46+
47+
Edit `docs/public/llms.txt` directly. Keep all URLs as absolute (`https://docs.mobileid.ch/…`). Update whenever pages are added or removed.
48+
49+
### Verification after deploy
50+
51+
```
52+
curl -s https://docs.mobileid.ch/robots.txt | head
53+
curl -s https://docs.mobileid.ch/sitemap.xml | head
54+
curl -s https://docs.mobileid.ch/llms.txt | head
55+
```

‎docs/.vitepress/config.mts‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,22 @@
1-
import { defineConfig } from 'vitepress'
1+
import { defineConfig, type HeadConfig } from 'vitepress'
22
import { full as emoji } from 'markdown-it-emoji'
33

4+
const SITE_URL = 'https://docs.mobileid.ch'
5+
46
// https://vitepress.dev/reference/site-config
57
export default defineConfig({
68
title: 'Mobile ID docs',
79
description: 'Technical documentation for Mobile ID integration',
10+
lang: 'en',
811
base: '/',
912
lastUpdated: true,
1013
// Enable the built-in light/dark appearance switch in the navbar
1114
appearance: true,
1215

16+
sitemap: {
17+
hostname: SITE_URL,
18+
},
19+
1320
markdown: {
1421
config: (md) => {
1522
md.use(emoji)
@@ -22,8 +29,31 @@ export default defineConfig({
2229
['link', { rel: 'shortcut icon', href: '/favicon.ico' }],
2330
['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/apple-touch-icon.png' }],
2431
['link', { rel: 'manifest', href: '/site.webmanifest' }],
32+
['meta', { name: 'robots', content: 'index, follow' }],
33+
['meta', { property: 'og:site_name', content: 'Mobile ID docs' }],
34+
['meta', { property: 'og:type', content: 'website' }],
35+
['meta', { property: 'og:locale', content: 'en' }],
36+
['meta', { name: 'twitter:card', content: 'summary' }],
2537
],
2638

39+
transformPageData(pageData) {
40+
const pagePath = pageData.relativePath
41+
.replace(/index\.md$/, '')
42+
.replace(/\.md$/, '.html')
43+
const canonicalUrl = `${SITE_URL}/${pagePath}`
44+
45+
const ogTitle = pageData.title || 'Mobile ID docs'
46+
const ogDesc = pageData.description || 'Technical documentation for Mobile ID integration'
47+
48+
pageData.frontmatter.head ??= []
49+
pageData.frontmatter.head.push(
50+
['link', { rel: 'canonical', href: canonicalUrl }],
51+
['meta', { property: 'og:title', content: ogTitle }],
52+
['meta', { property: 'og:description', content: ogDesc }],
53+
['meta', { property: 'og:url', content: canonicalUrl }],
54+
)
55+
},
56+
2757
themeConfig: {
2858
// https://vitepress.dev/reference/default-theme-config
2959
logo: '/img/mobileid-colors-transparent.svg',

‎docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
---
22
# https://vitepress.dev/reference/default-theme-home-page
33
layout: home
4+
title: Mobile ID docs
5+
description: Technical documentation for Mobile ID – seamless strong multi-factor authentication via REST API, OpenID Connect and RADIUS.
46

57
hero:
68
name: "Mobile ID docs"

‎docs/public/CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs.mobileid.ch

‎docs/public/llms.txt‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Mobile ID – Technical Documentation
2+
3+
> Mobile ID provides seamless strong multi-factor authentication.
4+
> This site contains integration guides for REST API, OpenID Connect (OIDC),
5+
> RADIUS gateway, and Passkey authentication.
6+
7+
## Main entry points
8+
9+
- Homepage: https://docs.mobileid.ch/
10+
- REST API Guide: https://docs.mobileid.ch/rest-api-guide/introduction.html
11+
- OIDC Integration Guide: https://docs.mobileid.ch/oidc-integration-guide/introduction.html
12+
- RADIUS Gateway Guide: https://docs.mobileid.ch/radius-interface-gateway-guide/introduction.html
13+
14+
## REST API Guide
15+
16+
- Introduction: https://docs.mobileid.ch/rest-api-guide/introduction.html
17+
- Integration Steps: https://docs.mobileid.ch/rest-api-guide/app-provider-client-integration.html
18+
- Mobile ID API: https://docs.mobileid.ch/rest-api-guide/mobile-id-api.html
19+
- Best Practices: https://docs.mobileid.ch/rest-api-guide/best-practices.html
20+
- Auto Activation: https://docs.mobileid.ch/rest-api-guide/auto-activation.html
21+
- Status and Fault Codes: https://docs.mobileid.ch/rest-api-guide/status-fault-codes.html
22+
- Root CA Certificates: https://docs.mobileid.ch/rest-api-guide/root-ca-certs.html
23+
- Create Client Certificates: https://docs.mobileid.ch/rest-api-guide/create-client-certs.html
24+
- Health Status Service: https://docs.mobileid.ch/rest-api-guide/health-status.html
25+
- Java Reference Client: https://docs.mobileid.ch/rest-api-guide/java-reference-client.html
26+
- Troubleshooting: https://docs.mobileid.ch/rest-api-guide/troubleshooting.html
27+
- API Specification (OpenAPI): https://docs.mobileid.ch/rest-api-guide/api-specification.html
28+
29+
## OIDC Integration Guide
30+
31+
- Introduction: https://docs.mobileid.ch/oidc-integration-guide/introduction.html
32+
- Getting Started: https://docs.mobileid.ch/oidc-integration-guide/getting-started.html
33+
- Best Practices: https://docs.mobileid.ch/oidc-integration-guide/best-practices.html
34+
- Passkey Authentication: https://docs.mobileid.ch/oidc-integration-guide/passkey-authentication.html
35+
- Public Cloud Integration: https://docs.mobileid.ch/oidc-integration-guide/cloud-integration-guide.html
36+
- OIDC Use Cases: https://docs.mobileid.ch/oidc-integration-guide/oidc-use-cases.html
37+
- App Message Formats: https://docs.mobileid.ch/oidc-integration-guide/message-formats.html
38+
39+
## RADIUS Gateway Guide
40+
41+
- Introduction: https://docs.mobileid.ch/radius-interface-gateway-guide/introduction.html
42+
- RIG Deployment: https://docs.mobileid.ch/radius-interface-gateway-guide/deployment.html
43+
- The RADIUS Protocol: https://docs.mobileid.ch/radius-interface-gateway-guide/radius-protocol.html
44+
- Annexes: https://docs.mobileid.ch/radius-interface-gateway-guide/annexes.html
45+
46+
## Additional resources
47+
48+
- Release Notes: https://docs.mobileid.ch/release-notes/release-notes.html
49+
- API Reference: https://docs.mobileid.ch/api-reference/api.html

‎docs/public/robots.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
User-agent: *
2+
Allow: /
3+
4+
Sitemap: https://docs.mobileid.ch/sitemap.xml

0 commit comments

Comments
 (0)