Skip to content

Commit bf93cf8

Browse files
oschwaldclaude
oschwald
and
claude
committed
Add Hugo-based docs site
Build with `mise run build-docs`, preview with `mise run serve-docs`. The site mounts the existing `README.md` as the home page so the source of truth stays in one place. A small pill nav links from Overview to the versioned API documentation that lives on the `gh-pages` branch under `doc/latest/`. CSS is inlined in the layout template — no external dependencies. Same Charter serif + forest-green design as the MaxMind-DB spec site. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 52b8255 commit bf93cf8

6 files changed

Lines changed: 284 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
_site
22
.gh-pages
33
.idea
4+
docs/.hugo_build.lock
5+
docs/public/
46
.php_cs.cache
57
.php-cs-fixer.cache
68
.phpunit.cache/

‎docs/hugo.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
baseURL = "https://maxmind.github.io/minfraud-api-php/"
2+
title = "minFraud PHP API"
3+
disableKinds = ["taxonomy"]
4+
5+
[[cascade]]
6+
layout = "default"
7+
8+
[markup.highlight]
9+
noClasses = true
10+
style = "github"
11+
12+
[[module.mounts]]
13+
source = "../README.md"
14+
target = "content/_index.md"

‎docs/layouts/_default/_markup/render-heading.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<h{{ .Level }} id="{{ .Anchor }}">
2+
{{- .Text | safeHTML -}}
3+
<a class="heading-anchor" href="#{{ .Anchor }}" aria-label="Link to {{ .PlainText }}">#</a>
4+
</h{{ .Level }}>

‎docs/layouts/_default/default.html‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1" />
6+
<title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ or .Title .File.BaseFileName }} | {{ .Site.Title }}{{ end }}</title>
7+
<style>
8+
:root {
9+
--fg: #2d2d2d;
10+
--bg: #faf9f7;
11+
--accent: #1a6b50;
12+
--accent-soft: rgba(26, 107, 80, 0.06);
13+
--border: #d5d0c8;
14+
--code-bg: #f0eeea;
15+
--heading: #1a1a1a;
16+
--muted: #70695f;
17+
}
18+
19+
::selection {
20+
background: rgba(26, 107, 80, 0.15);
21+
}
22+
23+
*,
24+
*::before,
25+
*::after {
26+
box-sizing: border-box;
27+
}
28+
29+
body {
30+
font-family: Charter, "Bitstream Charter", "Sitka Text", Cambria, serif;
31+
font-size: 1.05rem;
32+
line-height: 1.78;
33+
color: var(--fg);
34+
background: var(--bg);
35+
max-width: 50rem;
36+
margin: 0 auto;
37+
padding: 3rem 1.5rem 5rem;
38+
}
39+
40+
h1,
41+
h2,
42+
h3,
43+
h4 {
44+
font-family: system-ui, -apple-system, "Segoe UI", Helvetica, Arial,
45+
sans-serif;
46+
line-height: 1.35;
47+
}
48+
49+
h1 {
50+
font-size: 1.75rem;
51+
font-weight: 800;
52+
color: var(--heading);
53+
margin: 0 0 1.5rem;
54+
padding-bottom: 0.75rem;
55+
border-bottom: 3px solid var(--accent);
56+
}
57+
58+
h2 {
59+
font-size: 1.3rem;
60+
font-weight: 700;
61+
color: var(--heading);
62+
margin: 3rem 0 0.75rem;
63+
padding-bottom: 0.4rem;
64+
border-bottom: 1px solid var(--border);
65+
}
66+
67+
h3 {
68+
font-size: 1.05rem;
69+
font-weight: 700;
70+
color: var(--accent);
71+
margin: 2.5rem 0 0.5rem;
72+
padding: 0.4rem 0.75rem;
73+
border-left: 3px solid var(--accent);
74+
background: linear-gradient(
75+
135deg,
76+
var(--accent-soft),
77+
transparent 80%
78+
);
79+
border-radius: 0 3px 3px 0;
80+
}
81+
82+
h4 {
83+
font-size: 0.92rem;
84+
font-weight: 700;
85+
color: var(--muted);
86+
margin: 2rem 0 0.5rem;
87+
padding-bottom: 0.2rem;
88+
border-bottom: 1px dashed var(--border);
89+
}
90+
91+
p {
92+
margin: 0.8rem 0;
93+
}
94+
95+
a {
96+
color: var(--accent);
97+
text-decoration-thickness: 1px;
98+
text-underline-offset: 2px;
99+
transition: text-decoration-thickness 0.15s;
100+
}
101+
102+
a:hover {
103+
text-decoration-thickness: 2px;
104+
}
105+
106+
strong {
107+
color: var(--heading);
108+
font-weight: 700;
109+
}
110+
111+
ol,
112+
ul {
113+
padding-left: 1.75rem;
114+
}
115+
116+
li + li {
117+
margin-top: 0.3rem;
118+
}
119+
120+
code {
121+
font-family: "JetBrains Mono", "Cascadia Code", Menlo, Consolas,
122+
monospace;
123+
font-size: 0.88em;
124+
background: var(--code-bg);
125+
padding: 0.15em 0.4em;
126+
border-radius: 3px;
127+
border: 1px solid rgba(0, 0, 0, 0.06);
128+
}
129+
130+
pre {
131+
background: var(--code-bg);
132+
border: 1px solid var(--border);
133+
border-radius: 5px;
134+
padding: 1rem 1.25rem;
135+
overflow-x: auto;
136+
line-height: 1.55;
137+
}
138+
139+
pre code {
140+
background: none;
141+
padding: 0;
142+
border: none;
143+
font-size: 0.85em;
144+
}
145+
146+
.heading-anchor {
147+
opacity: 0;
148+
margin-left: 0.3em;
149+
font-weight: 400;
150+
text-decoration: none;
151+
transition: opacity 0.15s;
152+
}
153+
154+
h1:hover .heading-anchor,
155+
h2:hover .heading-anchor,
156+
h3:hover .heading-anchor,
157+
h4:hover .heading-anchor,
158+
.heading-anchor:focus {
159+
opacity: 0.4;
160+
}
161+
162+
.heading-anchor:hover {
163+
opacity: 1;
164+
}
165+
166+
.page-nav {
167+
margin-bottom: 2.5rem;
168+
display: flex;
169+
gap: 0.5rem;
170+
flex-wrap: wrap;
171+
}
172+
173+
.page-nav a {
174+
font-family: system-ui, -apple-system, "Segoe UI", Helvetica, Arial,
175+
sans-serif;
176+
font-size: 0.85rem;
177+
font-weight: 600;
178+
text-decoration: none;
179+
color: var(--muted);
180+
padding: 0.3rem 0.75rem;
181+
border: 1px solid var(--border);
182+
border-radius: 999px;
183+
transition: color 0.15s, border-color 0.15s, background 0.15s;
184+
}
185+
186+
.page-nav a:hover {
187+
color: var(--accent);
188+
border-color: var(--accent);
189+
}
190+
191+
.page-nav a.active {
192+
color: var(--bg);
193+
background: var(--accent);
194+
border-color: var(--accent);
195+
}
196+
</style>
197+
</head>
198+
<body>
199+
<nav class="page-nav">
200+
<a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>Overview</a>
201+
<a href="{{ "doc/latest/" | relURL }}">API documentation</a>
202+
</nav>
203+
<main>
204+
{{ .Content }}
205+
</main>
206+
</body>
207+
</html>

‎mise.lock‎

Lines changed: 33 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎mise.toml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[settings]
2+
lockfile = true
3+
disable_backends = [
4+
"asdf",
5+
"vfox",
6+
]
7+
8+
[tools]
9+
hugo = "latest"
10+
11+
[hooks]
12+
enter = "mise install --quiet"
13+
14+
[[watch_files]]
15+
patterns = ["mise.toml", "mise.lock"]
16+
run = "mise install --quiet"
17+
18+
[tasks.build-docs]
19+
description = "Build the docs site with Hugo"
20+
run = "hugo --source docs --minify"
21+
22+
[tasks.serve-docs]
23+
description = "Serve the docs site locally with Hugo dev server"
24+
run = "hugo server --source docs"

0 commit comments

Comments
 (0)