Skip to content

Commit d2b25af

Browse files
rphillips-ccrphillips-cc
authored
Merge pull request #86 from CloudCannon/feat/doc-overrides
Add override doc system
2 parents 3eef721 + 3489a1c commit d2b25af

12 files changed

Lines changed: 309 additions & 29 deletions

‎docs/docs.ts‎

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,8 @@ export async function moveOldDocs(folder: string, gidsInUse: Set<string>): Promi
7878
export async function writeNewDocs(
7979
folder: string,
8080
gids: Set<string>,
81-
pages: Record<string, Page>
81+
pages: Record<string, Page>,
82+
documentationEntries: Record<string, DocumentationEntry> = {}
8283
): Promise<void> {
8384
const folderPath = path.join(process.cwd(), folder);
8485
const pageFiles: any[] = [];
@@ -103,16 +104,41 @@ export async function writeNewDocs(
103104
newCount++;
104105
}
105106

107+
const page = pages[gid];
108+
109+
// Override-only doc entries (per-reference example overrides that resolve
110+
// to a shared type page) have no page of their own. Round-trip the
111+
// authored file as-is so its examples aren't clobbered on rebuild.
112+
if (!page) {
113+
const entry = documentationEntries[gid] as
114+
| (DocumentationEntry & { url?: string })
115+
| undefined;
116+
117+
if (entry) {
118+
pageFiles.push({
119+
gid,
120+
url: entry.url,
121+
title: entry.title || '',
122+
deprecated: entry.deprecated || undefined,
123+
deprecated_description: entry.deprecated_description || undefined,
124+
description: entry.description || '',
125+
examples: entry.examples || [],
126+
show_in_navigation: entry.show_in_navigation ?? false,
127+
});
128+
return;
129+
}
130+
}
131+
106132
pageFiles.push({
107133
gid,
108-
url: pages[gid]?.url,
109-
title: pages[gid]?.title || '',
110-
deprecated: pages[gid]?.deprecated || undefined,
111-
deprecated_description: pages[gid]?.deprecated_description || undefined,
112-
description: pages[gid]?.description || '',
113-
examples: pages[gid]?.examples || [],
134+
url: page?.url,
135+
title: page?.title || '',
136+
deprecated: page?.deprecated || undefined,
137+
deprecated_description: page?.deprecated_description || undefined,
138+
description: page?.description || '',
139+
examples: page?.examples || [],
114140
show_in_navigation:
115-
pages[gid]?.documentation?.show_in_navigation ??
141+
page?.documentation?.show_in_navigation ??
116142
(gid.startsWith('type.') && gid.split('.').length === 2),
117143
});
118144
});

‎docs/documentation/type._editables.*.code_block_options.language.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
gid: type._editables.*.code_block_options.language
2+
url: /configuration-file/types/_editables/*/code_block_options/language/
3+
title: ''
4+
description: This key defines the input for a code block's syntax highlighting language.
5+
examples:
6+
- description: >-
7+
In this example, we have configured the `language` input with a custom
8+
label, comment, and a limited set of selectable languages.
9+
language: yaml
10+
code: |-
11+
_editables:
12+
content:
13+
code_block_options:
14+
language:
15+
type: select
16+
label: Syntax language
17+
comment: Choose a syntax highlighting language for your code block
18+
options:
19+
values:
20+
- yaml
21+
- json
22+
- javascript
23+
annotations: []
24+
source: /cloudcannon.config.yml
25+
show_in_navigation: false

‎docs/documentation/type._editables.*.image_options.alt.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gid: type._editables.*.image_options.alt
2+
url: /configuration-file/types/_editables/*/image_options/alt/
3+
title: ''
4+
description: This key defines the input for an image's alternative text.
5+
examples:
6+
- description: >-
7+
In this example, we have configured the `alt` input with a custom label,
8+
comment, and placeholder.
9+
language: yaml
10+
code: |-
11+
_editables:
12+
content:
13+
image_options:
14+
alt:
15+
type: text
16+
label: Alt text
17+
comment: Describes the image for screen readers
18+
options:
19+
placeholder: A short description of the image
20+
annotations: []
21+
source: /cloudcannon.config.yml
22+
show_in_navigation: false

‎docs/documentation/type._editables.*.image_options.loading.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
gid: type._editables.*.image_options.loading
2+
url: /configuration-file/types/_editables/*/image_options/loading/
3+
title: ''
4+
description: This key defines the input for toggling lazy loading on an image.
5+
examples:
6+
- description: >-
7+
In this example, we have configured the `loading` input with a custom
8+
label and comment.
9+
language: yaml
10+
code: |-
11+
_editables:
12+
content:
13+
image_options:
14+
loading:
15+
type: switch
16+
label: Lazy load
17+
comment: Toggle lazy loading for this image
18+
annotations: []
19+
source: /cloudcannon.config.yml
20+
show_in_navigation: false

‎docs/documentation/type._editables.*.image_options.src.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
gid: type._editables.*.image_options.src
2+
url: /configuration-file/types/_editables/*/image_options/src/
3+
title: ''
4+
description: This key defines the input for the image file displayed.
5+
examples:
6+
- description: >-
7+
In this example, we have configured the `src` input with a custom label,
8+
comment, and accepted file types.
9+
language: yaml
10+
code: |-
11+
_editables:
12+
content:
13+
image_options:
14+
src:
15+
type: url
16+
label: Image file
17+
comment: The image file to display
18+
options:
19+
accepts_mime_types:
20+
- image/png
21+
- image/jpeg
22+
annotations: []
23+
source: /cloudcannon.config.yml
24+
show_in_navigation: false

‎docs/documentation/type._editables.*.image_options.title.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gid: type._editables.*.image_options.title
2+
url: /configuration-file/types/_editables/*/image_options/title/
3+
title: ''
4+
description: This key defines the input for an image's title text.
5+
examples:
6+
- description: >-
7+
In this example, we have configured the `title` input with a custom label,
8+
comment, and placeholder.
9+
language: yaml
10+
code: |-
11+
_editables:
12+
content:
13+
image_options:
14+
title:
15+
type: text
16+
label: Title
17+
comment: Tooltip text shown when hovering the image
18+
options:
19+
placeholder: Add a tooltip for this image
20+
annotations: []
21+
source: /cloudcannon.config.yml
22+
show_in_navigation: false

‎docs/documentation/type._editables.*.link_options.href.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gid: type._editables.*.link_options.href
2+
url: /configuration-file/types/_editables/*/link_options/href/
3+
title: ''
4+
description: This key defines the input for the destination URL of a hyperlink.
5+
examples:
6+
- description: >-
7+
In this example, we have configured the `href` input with a custom label,
8+
comment, and a hidden link option.
9+
language: yaml
10+
code: |-
11+
_editables:
12+
content:
13+
link_options:
14+
href:
15+
type: url
16+
label: Link URL
17+
comment: The destination this link points to
18+
options:
19+
hide_link_to_email_address: true
20+
annotations: []
21+
source: /cloudcannon.config.yml
22+
show_in_navigation: false

‎docs/documentation/type._editables.*.link_options.is_target_blank.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gid: type._editables.*.link_options.is_target_blank
2+
url: /configuration-file/types/_editables/*/link_options/is_target_blank/
3+
title: ''
4+
description: >-
5+
This key defines the input for toggling whether a hyperlink opens in a new
6+
browser tab.
7+
examples:
8+
- description: >-
9+
In this example, we have configured the `is_target_blank` input with a
10+
custom label and comment.
11+
language: yaml
12+
code: |-
13+
_editables:
14+
content:
15+
link_options:
16+
is_target_blank:
17+
type: switch
18+
label: Open in new tab
19+
comment: Open this link in a new browser tab
20+
annotations: []
21+
source: /cloudcannon.config.yml
22+
show_in_navigation: false

‎docs/documentation/type._editables.*.link_options.rel_nofollow.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gid: type._editables.*.link_options.rel_nofollow
2+
url: /configuration-file/types/_editables/*/link_options/rel_nofollow/
3+
title: ''
4+
description: >-
5+
This key defines the input for toggling whether `rel="nofollow"` is added to a
6+
hyperlink.
7+
examples:
8+
- description: >-
9+
In this example, we have configured the `rel_nofollow` input with a custom
10+
label and comment.
11+
language: yaml
12+
code: |-
13+
_editables:
14+
content:
15+
link_options:
16+
rel_nofollow:
17+
type: switch
18+
label: Add nofollow
19+
comment: Add rel="nofollow" to this link
20+
annotations: []
21+
source: /cloudcannon.config.yml
22+
show_in_navigation: false

‎docs/documentation/type._editables.*.link_options.rel_noreferrer.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gid: type._editables.*.link_options.rel_noreferrer
2+
url: /configuration-file/types/_editables/*/link_options/rel_noreferrer/
3+
title: ''
4+
description: >-
5+
This key defines the input for toggling whether `rel="noreferrer"` is added to
6+
a hyperlink.
7+
examples:
8+
- description: >-
9+
In this example, we have configured the `rel_noreferrer` input with a
10+
custom label and comment.
11+
language: yaml
12+
code: |-
13+
_editables:
14+
content:
15+
link_options:
16+
rel_noreferrer:
17+
type: switch
18+
label: Add noreferrer
19+
comment: Add rel="noreferrer" to this link
20+
annotations: []
21+
source: /cloudcannon.config.yml
22+
show_in_navigation: false

0 commit comments

Comments
 (0)