Skip to content

Commit 829d8e0

Browse files
rosieyohannanrosieyohannan
authored
Api docs v2 formatting (#200)
* claude's attempt to configure how api v2 looks * fix up some styling for the api v2 docs * logo link back to API docs
1 parent 92dbbff commit 829d8e0

File tree

4 files changed

+150
-6
lines changed

4 files changed

+150
-6
lines changed

‎custom-template.hbs

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<!DOCTYPE html>
2+
<html>
3+
4+
<head>
5+
<meta charset="utf8" />
6+
<title>{{title}}</title>
7+
<!-- needed for adaptive design -->
8+
<meta name="viewport" content="width=device-width, initial-scale=1">
9+
<style>
10+
body {
11+
padding: 0;
12+
margin: 0;
13+
}
14+
15+
/* Custom logo styling - properly centered and clickable */
16+
.custom-logo {
17+
position: fixed;
18+
top: 15px;
19+
left: 15px;
20+
z-index: 1001;
21+
padding: 12px; /* Equal padding on all sides */
22+
display: flex;
23+
align-items: center;
24+
justify-content: center;
25+
width: fit-content;
26+
transition: all 0.2s ease;
27+
}
28+
29+
.custom-logo a:hover {
30+
transform: translateY(-1px);
31+
}
32+
33+
.custom-logo img {
34+
height: 32px;
35+
width: auto;
36+
display: block;
37+
}
38+
39+
/* Adjust sidebar to avoid logo overlap */
40+
.menu-content {
41+
padding-top: 70px !important;
42+
}
43+
44+
/* Hide logo on very small screens to avoid clutter */
45+
@media (max-width: 480px) {
46+
.custom-logo {
47+
display: none;
48+
}
49+
}
50+
51+
/* Adjust for medium screens */
52+
@media (max-width: 768px) {
53+
.custom-logo {
54+
position: relative;
55+
top: 0;
56+
left: 0;
57+
margin: 15px auto;
58+
display: block;
59+
text-align: center;
60+
max-width: none;
61+
width: fit-content;
62+
padding: 15px 20px;
63+
}
64+
65+
.menu-content {
66+
padding-top: 20px !important;
67+
}
68+
}
69+
</style>
70+
{{{redocHead}}}
71+
{{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
72+
</head>
73+
74+
<body>
75+
<!-- Clickable logo that routes to docs homepage -->
76+
<div class="custom-logo">
77+
<a href="../../reference/api-homepage.html" title="Back to CircleCI Documentation">
78+
<img src="logo.svg" alt="CircleCI" />
79+
</a>
80+
</div>
81+
82+
{{{redocHTML}}}
83+
</body>
84+
85+
</html>

‎gulp.d/tasks/build-api-docs.js

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -183,19 +183,50 @@ function buildApiV2(callback) {
183183
// STEP 6: Build final HTML documentation
184184
// Redocly transforms the OpenAPI spec into beautiful, interactive docs
185185
console.log('🏗️ Building docs with Redocly CLI...')
186-
exec('npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json --output build/api/v2/index.html', (err, stdout, stderr) => {
186+
187+
// Build options for enhanced customization (all free options):
188+
// --title: Custom page title
189+
// --theme.openapi.disableSearch: Disable search (if needed)
190+
// --theme.openapi.hideDownloadButton: Hide download button
191+
// --template: Custom template (requires template file)
192+
// --options.maxDisplayedEnumValues: Limit enum display
193+
194+
const buildCommand = [
195+
'npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json',
196+
'--output build/api/v2/index.html',
197+
'--config redocly.yaml',
198+
'--template custom-template.hbs',
199+
'--title "CircleCI API v2 Documentation"',
200+
'--disableGoogleFont=false',
201+
// Additional options for free version:
202+
// '--theme.openapi.hideDownloadButton=true',
203+
// '--theme.openapi.disableSearch=true',
204+
// '--theme.openapi.nativeScrollbars=true'
205+
].join(' ')
206+
207+
exec(buildCommand, (err, stdout, stderr) => {
187208
if (err) {
188209
console.error('❌ Failed to build API docs:', err)
189210
return callback(err)
190211
}
191212

192213
console.log('✅ API v2 docs built successfully')
193214

194-
// STEP 7: Cleanup temporary files
195-
// Remove intermediate files to keep build directory clean
196-
exec('rm -rf build/temp-api-v2', () => {
197-
console.log('🎉 API v2 documentation build completed!')
198-
callback()
215+
// STEP 7: Copy logo file for template
216+
console.log('📋 Copying logo file...')
217+
exec('cp logo.svg build/api/v2/', (err) => {
218+
if (err) {
219+
console.warn('⚠️ Warning: Could not copy logo file:', err.message)
220+
} else {
221+
console.log('✅ Logo file copied successfully')
222+
}
223+
224+
// STEP 8: Cleanup temporary files
225+
// Remove intermediate files to keep build directory clean
226+
exec('rm -rf build/temp-api-v2', () => {
227+
console.log('🎉 API v2 documentation build completed!')
228+
callback()
229+
})
199230
})
200231
})
201232
})

‎logo.svg

Lines changed: 3 additions & 0 deletions
Loading

‎redocly.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,27 @@
11
extends:
22
- recommended
3+
4+
theme:
5+
openapi:
6+
theme:
7+
colors:
8+
primary:
9+
main: '#2152E5' # CircleCI blue
10+
http:
11+
get: '#61AFFE'
12+
post: '#49CC90'
13+
put: '#FCA130'
14+
delete: '#F93E3E'
15+
text:
16+
primary: '#333333'
17+
typography:
18+
fontSize: '16px'
19+
fontFamily: 'Inter, sans-serif'
20+
# Additional options for free version
21+
disableSearch: false
22+
hideDownloadButton: false
23+
hideLoading: false
24+
nativeScrollbars: false
25+
26+
# Title and description are set via the build command
27+
# Use --title "CircleCI API v2 Documentation" in the build command

0 commit comments

Comments
 (0)