From 57dcca6bff73698c10116b4846a655f3f0da087c Mon Sep 17 00:00:00 2001 From: Ross Phillips <12723297+rphillips-cc@users.noreply.github.com> Date: Sat, 23 Nov 2024 21:51:58 +1300 Subject: [PATCH 1/2] Iterating on documentation --- .gitignore | 2 + src/build-coupled.d.ts | 12 +- src/configuration.d.ts | 395 ++++++++++++++++++++++++++++------------- src/index.d.ts | 19 ++ src/markdown.d.ts | 25 +-- 5 files changed, 316 insertions(+), 137 deletions(-) diff --git a/.gitignore b/.gitignore index b947077..a8eb998 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ node_modules/ dist/ +.zed/ +.vscode/ diff --git a/src/build-coupled.d.ts b/src/build-coupled.d.ts index 5c45ce9..a828102 100644 --- a/src/build-coupled.d.ts +++ b/src/build-coupled.d.ts @@ -137,11 +137,11 @@ export type EleventyConfiguration = JekyllConfiguration; export type ParsedDataset = | string[] | Record - | Record> - | Record[]; + | Record> + | Record[]; interface ParsedCollectionItem { - [index: string]: any; + [index: string]: unknown; /** * The path to the file this was parsed from. */ @@ -201,12 +201,12 @@ interface WithIntegrationOutput { /** * The output from build-coupled non-Jekyll/Hugo/Eleventy sites. */ -export interface IntegrationOutput extends Configuration, WithIntegrationOutput {} +export type IntegrationOutput = Configuration & WithIntegrationOutput; /** * The output from build-coupled Hugo sites. */ -export interface HugoIntegrationOutput extends HugoConfiguration, WithIntegrationOutput {} +export type HugoIntegrationOutput = HugoConfiguration & WithIntegrationOutput; /** * The output from build-coupled Jekyll sites. @@ -221,4 +221,4 @@ export interface JekyllIntegrationOutput extends JekyllConfiguration, WithIntegr /** * The output from build-coupled Eleventy sites. */ -export interface EleventyIntegrationOutput extends EleventyConfiguration, WithIntegrationOutput {} +export type EleventyIntegrationOutput = EleventyConfiguration & WithIntegrationOutput; diff --git a/src/configuration.d.ts b/src/configuration.d.ts index 93396c6..e349308 100644 --- a/src/configuration.d.ts +++ b/src/configuration.d.ts @@ -33,7 +33,7 @@ export interface SnippetConfig extends ReducedCascade, WithPreview, WithPickerPr /** * The variables required for the selected template. */ - definitions?: Record; + definitions?: Record; /** * Alternate configurations for this snippet. */ @@ -41,7 +41,7 @@ export interface SnippetConfig extends ReducedCascade, WithPreview, WithPickerPr /** * The parameters of this snippet. */ - params?: Record; // TODO: use ParserConfig from @cloudcannon/scrap-booker. + params?: Record; // TODO: use ParserConfig from @cloudcannon/scrap-booker. } export interface SnippetsImports { @@ -54,6 +54,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -61,6 +63,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -73,6 +77,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -80,6 +86,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -92,6 +100,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -99,6 +109,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -111,6 +123,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -118,6 +132,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -130,6 +146,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -137,6 +155,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -149,6 +169,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -156,6 +178,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -168,6 +192,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -175,6 +201,8 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; @@ -187,6 +215,8 @@ export interface SnippetsImports { /** * The list of excluded snippets. If unset, all snippets are excluded unless defined in * `include`. + * + * @uniqueItems */ exclude: Array; } @@ -194,30 +224,13 @@ export interface SnippetsImports { /** * The list of included snippets. If unset, all snippets are included unless defined in * `exclude`. + * + * @uniqueItems */ include: Array; }; } -interface WithSnippets { - /** - * Configuration for custom snippets. - */ - _snippets?: Record; - /** - * Provides control over which snippets are available to use and/or extend within `_snippets`. - */ - _snippets_imports?: SnippetsImports; - /** - * Extended option used when creating more complex custom snippets. - */ - _snippets_templates?: Record; - /** - * Extended option used when creating more complex custom snippets. - */ - _snippets_definitions?: Record; -} - interface ImageResizeable { /** * Sets the format images are converted to prior to upload. The extension of the file is updated @@ -310,11 +323,15 @@ export interface Editables { export interface BlockEditable extends ImageResizeable, TextEditable { /** * Enables a control to wrap blocks of text in block quotes. + * + * @default true */ blockquote?: boolean; /** * Enables a control to insert an unordered list, or to convert selected blocks of text into a * unordered list. + * + * @default true */ bulletedlist?: boolean; /** @@ -325,37 +342,53 @@ export interface BlockEditable extends ImageResizeable, TextEditable { center?: string; /** * Enables a control to create an inline code element, containing any selected text. + * + * @default false */ code_inline?: boolean; /** * Enables a control to insert a code block. + * + * @default false */ code_block?: boolean; /** * Enables both block and inline code controls: `code_block` and `code_inline`. + * + * @default false */ code?: boolean; /** * Enables a control to insert a region of raw HTML, including YouTube, Vimeo, Tweets, and other * media. Embedded content is sanitized to mitigate XSS risks, which includes removing style tags. * Embeds containing script tags are not loaded in the editor. + * + * @default false */ embed?: boolean; /** * Enables a drop down menu for structured text. Has options for "p", "h1", "h2", "h3", "h4", * "h5", "h6". Set as space separated options (e.g. "p h1 h2"). + * + * @default p h1 h2 h3 h4 h5 h6 */ format?: string; /** * Enables a control to insert a horizontal rule. + * + * @default false */ horizontalrule?: boolean; /** * Enables a control to insert an image. The image can be uploaded, existing or an external link. + * + * @default true */ image?: boolean; /** * Enables a control to increase indentation for numbered and unordered lists. + * + * @default false */ indent?: boolean; /** @@ -373,10 +406,14 @@ export interface BlockEditable extends ImageResizeable, TextEditable { /** * Enables a control to insert a numbered list, or to convert selected blocks of text into a * numbered list. + * + * @default true */ numberedlist?: boolean; /** * Enables a control to reduce indentation for numbered and unordered lists. + * + * @default false */ outdent?: boolean; /** @@ -387,6 +424,8 @@ export interface BlockEditable extends ImageResizeable, TextEditable { right?: string; /** * Enables a control to insert snippets, if any are available. + * + * @default true */ snippet?: boolean; /** @@ -398,6 +437,8 @@ export interface BlockEditable extends ImageResizeable, TextEditable { /** * Enables a control to insert a table. Further options for table cells are available in the * context menu for cells within the editor. + * + * @default false */ table?: boolean; } @@ -411,59 +452,81 @@ interface WithPaths { paths?: Paths; } -export interface ImageEditable extends ImageResizeable, WithPaths {} +export type ImageEditable = ImageResizeable & WithPaths; -export interface LinkEditable extends WithPaths {} +export type LinkEditable = WithPaths; export interface TextEditable extends WithPaths { /** * Enables a control to set selected text to bold. + * + * @default true */ bold?: boolean; /** * Enables a control to copy formatting from text to other text. Only applies to formatting from * `bold`, `italic`, `underline`, `strike`, `subscript`, and `superscript`. Does not copy other * styles or formatting. + * + * @default false */ copyformatting?: boolean; /** * Enables a control to italicize selected text. + * + * @default true */ italic?: boolean; /** * Enables a control to create hyperlinks around selected text. + * + * @default true */ link?: boolean; /** * Enables a control to redo recent edits undone with undo. Redo is always enabled through * standard OS-specific keyboard shortcuts. + * + * @default false */ redo?: boolean; /** * Enables the control to remove formatting from text. Applies to formatting from `bold`, * `italic`, `underline`, `strike`, `subscript`, and `superscript`. Does not remove other styles * or formatting. + * + * @default true */ removeformat?: boolean; /** * Enables a control to strike selected text. + * + * @default false */ strike?: boolean; /** * Enables a control to set selected text to subscript. + * + * @default false */ subscript?: boolean; /** * Enables a control to set selected text to superscript. + * + * @default false */ superscript?: boolean; /** * Enables a control to underline selected text. + * + * @default false */ underline?: boolean; /** * Enables a control to undo recent edits. Undo is always enabled through standard OS-specific * keyboard shortcuts. + * + * @default false */ undo?: boolean; /** @@ -511,17 +574,17 @@ export interface Cascade extends ReducedCascade { /** * Now known as _structures. * - * @deprecated Use _structures instead. + * @deprecated Use `_structures` instead. */ _array_structures?: Record; /** - * Now part of _inputs.*.comment. + * Now part of `_inputs.*.comment`. * * @deprecated Use _inputs instead. */ _comments?: Record; /** - * Now part of _inputs.*.options. + * Now part of `_inputs.*.options`. * * @deprecated Use _inputs instead. */ @@ -558,43 +621,42 @@ export type InputType = | 'choice' | 'multichoice' | 'object' - | 'array'; - -export type EmptyTypeText = 'null' | 'string'; -export type EmptyTypeNumber = 'null' | 'number'; -export type EmptyTypeArray = 'null' | 'array'; -export type EmptyTypeObject = 'null' | 'object'; + | 'array' + | 'auto'; interface WithEmptyTypeText { /** * Set how an ‘empty’ value will be saved. Does not apply to existing empty values. */ - empty_type?: EmptyTypeText; + empty_type?: 'null' | 'string'; } interface WithEmptyTypeNumber { /** * Set how an ‘empty’ value will be saved. Does not apply to existing empty values. */ - empty_type?: EmptyTypeNumber; + empty_type?: 'null' | 'number'; } interface WithEmptyTypeObject { /** * Set how an ‘empty’ value will be saved. Does not apply to existing empty values. */ - empty_type?: EmptyTypeObject; + empty_type?: 'null' | 'object'; } interface WithEmptyTypeArray { /** * Set how an ‘empty’ value will be saved. Does not apply to existing empty values. */ - empty_type?: EmptyTypeArray; + empty_type?: 'null' | 'array'; } export interface BaseInput { - type?: InputType | undefined | null; + /** + * Sets an input type, which controls how this input appears and behaves. + */ + type?: InputType; /** * Options that are specific to this `type` of input. */ @@ -647,8 +709,6 @@ export interface BaseInput { /** * Specifies whether or not this input configuration should be merged with any matching, less * specific configuration. - * - * @default true */ cascade?: boolean; } @@ -684,6 +744,8 @@ export interface TextInput extends BaseInput { export interface TextareaInputOptions extends TextInputOptions { /** * Shows a character counter below the input if enabled. + * + * @default false */ show_count?: boolean; } @@ -773,9 +835,25 @@ export interface NumberInput extends BaseInput { } export interface RangeInputOptions extends NumberInputOptions { - min: number; - max: number; - step: number; + /** + * The lowest value in the range of permitted values. + * + * @default 0 + */ + min?: number; + /** + * The greatest value in the range of permitted values. + * + * @default 10 + */ + max?: number; + /** + * A number that specifies the granularity that the value must adhere to, or the special value + * any, which allows any decimal value between `max` and `min`. + * + * @default 1 + */ + step?: number; } export interface RangeInput extends BaseInput { @@ -799,10 +877,14 @@ export interface UrlInput extends BaseInput { export interface RichTextInputOptions extends WithEmptyTypeText, ImageResizeable, BlockEditable { /** * Shows or hides the resize handler to vertically resize the input. + * + * @default false */ allow_resize?: boolean; /** * Defines the initial height of this input in pixels (px). + * + * @default 320 */ initial_height?: number; } @@ -819,6 +901,8 @@ export interface DateInputOptions extends WithEmptyTypeText { /** * Specifies the time zone that dates are displayed and edited in. Also changes the suffix the * date is persisted to the file with. Defaults to the global `timezone`. + * + * @default Etc/UTC */ timezone?: Timezone; } @@ -931,16 +1015,36 @@ export interface MultichoiceInput extends BaseInput { } export interface ObjectInputGroup { + /** + * The main text for the group shown when collapsed or expanded. + */ heading?: string; + /** + * Changes the subtext below the `heading`. Has no default. Supports a limited set of Markdown: + * links, bold, italic, subscript, superscript, and inline code elements are allowed. + */ comment?: string; + /** + * Controls if this group is collapsed or expanded when first viewed. + * + * @default false + */ collapsed?: boolean; + /** + * The keys of each input in this group. + */ inputs?: string[]; + /** + * Provides a custom link for documentation for editors shown above the collection file list. + */ documentation?: Documentation; } export interface ObjectInputOptions extends WithEmptyTypeObject, WithPreview { /** * Changes the appearance and behavior of the input. + * + * @default object */ subtype?: 'object' | 'mutable' | 'tabbed'; /** @@ -971,19 +1075,20 @@ export interface ObjectInputOptions extends WithEmptyTypeObject, WithPreview { * itself. */ structures?: string | Structure; - /** * Allows you to group the inputs inside this object together without changing the data structure. */ groups?: ObjectInputGroup[]; - /** * Controls which order input groups and ungrouped inputs appear in. + * + * @default false */ place_groups_below?: boolean; - /** * Controls whether or not labels on mutable object entries are formatted. + * + * @default false */ allow_label_formatting?: boolean; /** @@ -1017,8 +1122,7 @@ export interface ArrayInput extends BaseInput { } export interface UnknownInput extends BaseInput { - type?: undefined | null; - + type?: 'auto' | undefined; /** * Options that are specific to this `type` of input. */ @@ -1054,7 +1158,7 @@ export interface Paths { /** * Default location of newly uploaded site files. * - * @default 'uploads' + * @default uploads */ uploads?: string; /** @@ -1063,8 +1167,6 @@ export interface Paths { uploads_filename?: string; /** * Default location of newly uploaded DAM files. - * - * @default '' */ dam_uploads?: string; /** @@ -1074,8 +1176,6 @@ export interface Paths { /** * Location of statically copied assets for DAM files. This prefix will be removed from the _DAM * Uploads_ path when CloudCannon outputs the URL of an asset. - * - * @default '' */ dam_static?: string; /** @@ -1096,6 +1196,8 @@ export interface Documentation { text?: string; /** * The icon displayed next to the link. + * + * @default auto_stories */ icon?: Icon; } @@ -1151,6 +1253,8 @@ export interface PreviewGallery WithIconColorPreview { /** * Controls how the gallery image is positioned within the gallery. + * + * @default padded */ fit?: 'padded' | 'cover' | 'contain' | 'cover-top'; } @@ -1177,50 +1281,56 @@ export interface Preview gallery?: PreviewGallery; } -export interface AddOption { - /** - * The text displayed for the menu item. Defaults to using name from the matching schema if set. - */ - name?: string; - /** - * The icon next to the text in the menu item. Defaults to using icon from the matching schema if - * set, then falls back to add. - */ - icon?: Icon; - /** - * The editor to open the new file in. Defaults to an appropriate editor for new file's type if - * possible. If no default editor can be calculated, or the editor does not support the new file - * type, a warning is shown in place of the editor. - */ - editor?: EditorKey; - /** - * Enforces a path for new files to be created in, regardless of path the user is currently - * navigated to within the collection file list. Relative to the path of the collection defined in - * collection. Defaults to the path within the collection the user is currently navigated to. - */ - base_path?: string; - /** - * Sets which collection this action is creating a file in. This is used when matching the value - * for schema. Defaults to the containing collection these `add_options` are configured in. - */ - collection?: string; - /** - * The schema that new files are created from with this action. This schema is not restricted to - * the containing collection, and is instead relative to the collection specified with collection. - * Defaults to default if schemas are configured for the collection. - */ - schema?: string; - /** - * The path to a file used to populate the initial contents of a new file if no schemas are - * configured. We recommend using schemas, and this is ignored if a schema is available. - */ - default_content_file?: string; - /** - * The link that opens when the option is clicked. Can either be an external or internal link. If - * internal, the link is relative to the current site. - */ - href?: string; -} +export type AddOption = + | { + /** + * The text displayed for the menu item. Defaults to using name from the matching schema if + * set. + */ + name?: string; + /** + * The icon next to the text in the menu item. Defaults to using icon from the matching schema + * if set, then falls back to add. + */ + icon?: Icon; + /** + * The editor to open the new file in. Defaults to an appropriate editor for new file's type + * if possible. If no default editor can be calculated, or the editor does not support the new + * file type, a warning is shown in place of the editor. + */ + editor?: EditorKey; + /** + * Enforces a path for new files to be created in, regardless of path the user is currently + * navigated to within the collection file list. Relative to the path of the collection + * defined in collection. Defaults to the path within the collection the user is currently + * navigated to. + */ + base_path?: string; + /** + * Sets which collection this action is creating a file in. This is used when matching the + * value for schema. Defaults to the containing collection these `add_options` are configured + * in. + */ + collection?: string; + /** + * The schema that new files are created from with this action. This schema is not restricted + * to the containing collection, and is instead relative to the collection specified with + * collection. Defaults to default if schemas are configured for the collection. + */ + schema?: string; + /** + * The path to a file used to populate the initial contents of a new file if no schemas are + * configured. We recommend using schemas, and this is ignored if a schema is available. + */ + default_content_file?: string; + } + | { + /** + * The link that opens when the option is clicked. Can either be an external or internal link. + * If internal, the link is relative to the current site. + */ + href: string; + }; interface WithPreview { /** @@ -1271,6 +1381,8 @@ export interface Schema extends Cascade, WithPreview, SchemaBase { /** * Displayed in the add menu when creating new files; also used as the icon for collection files * if no other preview is found. Defaults to notes. + * + * @default notes */ icon?: Icon; /** @@ -1326,9 +1438,9 @@ export interface Create extends ReducedCascade { export interface CollectionConfig extends Cascade, WithPreview { /** - * The top-most folder where the files in this collection are stored. It is relative to source. + * The top-most folder where the files in this collection are stored. It is relative to `source`. */ - path?: string; + path: string; /** * Glob pattern(s) to include or exclude files from this collection. It is relative to `path`. */ @@ -1359,6 +1471,8 @@ export interface CollectionConfig extends Cascade, WithPreview { description?: string; /** * Sets an icon to use alongside references to this collection. + * + * @default notes */ icon?: Icon; /** @@ -1454,6 +1568,8 @@ export interface Structure extends SchemaBase { /** * Defines whether options are shown to your editors in a select menu (select, default) or a modal * pop up window (modal) when adding a new item. + * + * @default select */ style?: 'select' | 'modal'; } @@ -1469,6 +1585,8 @@ export interface StructureValue extends WithPreview, WithPickerPreview, SchemaBa * of a value within a structure cannot be inferred based on its id_key or matching fields, then * it will fall back to this item. If multiple items have default set to true, only the first item * will be used. + * + * @default false */ default?: boolean; /** @@ -1495,10 +1613,14 @@ export interface StructureValue extends WithPreview, WithPickerPreview, SchemaBa groups?: ObjectInputGroup[]; /** * Controls which order input groups and ungrouped inputs appear in. + * + * @default false */ place_groups_below?: boolean; /** * Show nested objects as tabs. Requires all top-level keys to be objects. + * + * @default false */ tabbed?: boolean; /** @@ -1565,7 +1687,7 @@ export interface CommitTemplate { */ label?: string; /** - * Set the string for the commit template. This will only be used if template_path is not set. + * Set the string for the commit template. This will only be used if `template_path` is not set. */ template_string?: string; /** @@ -1583,77 +1705,108 @@ export interface CommitTemplate { extra_data?: Record; } -export type SsgKey = - | 'hugo' - | 'jekyll' - | 'eleventy' - | 'astro' - | 'lume' - | 'mkdocs' - | 'nextjs' - | 'sveltekit' - | 'bridgetown' - | 'docusaurus' - | 'gatsby' - | 'hexo' - | 'nuxtjs' - | 'sphinx' - | 'static' - | 'legacy' - | 'other'; - /** * The base format for the configuration file. */ -export interface Configuration extends Cascade, WithSnippets, WithPaths { +export interface Configuration extends Cascade, WithPaths { /** - * Base path to your site source files, relative to the root folder. + * This key defines the base path for your source files, relative to the root folder of your + * repository. Unless you use a nested folder as the source for your Site you can leave this key + * empty or set it to `/`. + * + * By default, this key is empty. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#source */ source?: string; /** * Definitions for your collections, which are the sets of content files for your site grouped by * folder. Entries are keyed by a chosen collection key, and contain configuration specific to * that collection. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#collections_config */ collections_config?: Record; /** * Defines which collections are shown in the site navigation and how those collections are * grouped. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#collections_groups */ collection_groups?: CollectionGroup[]; /** * The subpath where your output files are hosted. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#base_url */ base_url?: string; /** * Controls what data sets are available to populate select and multiselect inputs. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#data_config */ data_config?: Record; /** * Provides scope to configure at a file level, without adding configuration to files. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#file_config */ - file_config?: Record; + file_config?: FileConfigEntry[]; /** * Contains settings for the default editor actions on your site. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#editor.default_path */ editor?: Editor; /** * Settings for the behavior and appearance of the Source Editor. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#source_editor */ source_editor?: SourceEditor; /** * Templates for commit messages when saving changes. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#commit_templates */ commit_templates?: CommitTemplate[]; /** * Contains settings for various Markdown engines. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#markdown */ markdown?: MarkdownSettings; /** * Specifies the time zone that dates are displayed and edited in. Also changes the suffix the * date is persisted to the file with. * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#timezone + * * @default Etc/UTC */ timezone?: Timezone; + /** + * Configuration for custom snippets. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#_snippets + */ + _snippets?: Record; + /** + * Provides control over which snippets are available to use and/or extend within `_snippets`. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#_snippets_imports + */ + _snippets_imports?: SnippetsImports; + /** + * Extended option used when creating more complex custom snippets. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#_snippets_templates + */ + _snippets_templates?: Record; + /** + * Extended option used when creating more complex custom snippets. + * + * https://cloudcannon.com/documentation/articles/configuration-file-reference/#_snippets_definitions + */ + _snippets_definitions?: Record; } diff --git a/src/index.d.ts b/src/index.d.ts index 8e8cb23..2f7d24f 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -6,3 +6,22 @@ export type * from './syntax'; export type * from './markdown'; export type * from './configuration'; export type * from './build-coupled'; + +export type SsgKey = + | 'hugo' + | 'jekyll' + | 'eleventy' + | 'astro' + | 'lume' + | 'mkdocs' + | 'nextjs' + | 'sveltekit' + | 'bridgetown' + | 'docusaurus' + | 'gatsby' + | 'hexo' + | 'nuxtjs' + | 'sphinx' + | 'static' + | 'legacy' + | 'other'; diff --git a/src/markdown.d.ts b/src/markdown.d.ts index 80b5972..d0cfa97 100644 --- a/src/markdown.d.ts +++ b/src/markdown.d.ts @@ -14,6 +14,11 @@ export type MarkdownAttributeElementOptions = { }; export interface MarkdownSettings { + /** + * The flavor of Markdown to use to convert between HTML and Markdown. + * + * @default kramdown + */ engine: 'commonmark' | 'kramdown'; options: { /** @@ -21,11 +26,11 @@ export interface MarkdownSettings { */ html?: boolean; /** - * Use '/' to close single tags (
). + * Use `/` to close single tags (e.g. `
`). */ xhtml?: boolean; /** - * Convert '\n' in paragraphs into
. + * Convert `\n` in paragraphs into `
`. */ breaks?: boolean; /** @@ -33,13 +38,13 @@ export interface MarkdownSettings { */ linkify?: boolean; /** - * Enable some language-neutral replacement + quotes beautification. + * Enable some language-neutral replacement, as well as quotes beautification. */ typographer?: boolean; /** * Double + single quotes replacement pairs, when typographer enabled and smartquotes on. For - * example, you can use '«»„“' for Russian, '„“‚‘' for German, and ['«\xA0', '\xA0»', '‹\xA0', - * '\xA0›'] for French (including nbsp). + * example, you can use `'«»„“'` for Russian, `'„“‚‘'` for German, and `['«\xA0', '\xA0»', + * '‹\xA0', '\xA0›']` for French (including `nbsp`). */ quotes?: string; /** @@ -71,19 +76,19 @@ export interface MarkdownSettings { */ table?: boolean; /** - * Output strikes in wrapped in double tildes (e.g. ~~strike~~) + * Output strikes in wrapped in double tildes (e.g. `~~strike~~`). */ strikethrough?: boolean; /** - * Output subscript in wrapped in tildes (e.g. ~sub~) + * Output subscript in wrapped in tildes (e.g. `~sub~`). */ subscript?: boolean; /** - * Output superscript in wrapped in carets (e.g. ^super^) + * Output superscript in wrapped in carets (e.g. `^super^`). */ superscript?: boolean; /** - * Generate IDs for headings + * Generate IDs for headings. */ heading_ids?: boolean; /** @@ -91,7 +96,7 @@ export interface MarkdownSettings { */ attributes?: boolean; /** - * Define positioning behaviour of Markdown attributes for different elements. + * Define positioning behavior of Markdown attributes for different elements. */ attribute_elements?: MarkdownAttributeElementOptions; }; From 13a732150eaf7d9cbef4574d9a54270058bab9d2 Mon Sep 17 00:00:00 2001 From: Ross Phillips <12723297+rphillips-cc@users.noreply.github.com> Date: Fri, 29 Nov 2024 11:25:55 +1300 Subject: [PATCH 2/2] fix: add missing types --- .gitignore | 2 -- src/build-coupled.d.ts | 2 +- src/configuration.d.ts | 55 ++++++++++++++++++------------------- test/cloudcannon.config.yml | 12 ++++++++ 4 files changed, 40 insertions(+), 31 deletions(-) diff --git a/.gitignore b/.gitignore index a8eb998..b947077 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,2 @@ node_modules/ dist/ -.zed/ -.vscode/ diff --git a/src/build-coupled.d.ts b/src/build-coupled.d.ts index a828102..bc77c18 100644 --- a/src/build-coupled.d.ts +++ b/src/build-coupled.d.ts @@ -149,7 +149,7 @@ interface ParsedCollectionItem { /** * The collection key this is assigned to. Matches keys in `collections_config`. */ - collection: string; + collection?: string; /** * The URL this file is served at once built. */ diff --git a/src/configuration.d.ts b/src/configuration.d.ts index e349308..a373b5a 100644 --- a/src/configuration.d.ts +++ b/src/configuration.d.ts @@ -1,11 +1,11 @@ import type Scrapbooker from '@cloudcannon/snippet-types'; import type { Icon } from './icon'; -import type { Timezone } from './timezone'; +import type { MarkdownSettings } from './markdown'; import type { MimeType } from './mime-type'; -import type { Theme } from './theme'; import type { Syntax } from './syntax'; -import type { MarkdownSettings } from './markdown'; +import type { Theme } from './theme'; +import type { Timezone } from './timezone'; export type InstanceValue = 'UUID' | 'NOW'; export type EditorKey = 'visual' | 'content' | 'data'; @@ -26,6 +26,10 @@ export interface SnippetConfig extends ReducedCascade, WithPreview, WithPickerPr * this snippet as a block-level element in the content editor. */ inline?: boolean; + /** + * Controls how selected items are rendered. Defaults to 'card', or 'inline' if `inline` is true. + */ + view?: 'card' | 'inline' | 'gallery'; /** * Whether this snippet treats whitespace as-is or not. */ @@ -571,24 +575,6 @@ export interface Cascade extends ReducedCascade { * Contains input options for Editable Regions and the Content Editor. */ _editables?: Editables; - /** - * Now known as _structures. - * - * @deprecated Use `_structures` instead. - */ - _array_structures?: Record; - /** - * Now part of `_inputs.*.comment`. - * - * @deprecated Use _inputs instead. - */ - _comments?: Record; - /** - * Now part of `_inputs.*.options`. - * - * @deprecated Use _inputs instead. - */ - _options?: Record>; } export type InputType = @@ -910,16 +896,18 @@ export interface DateInputOptions extends WithEmptyTypeText { export interface DateInput extends BaseInput { type: 'date' | 'datetime'; /** - * Options that are specific to this `type` of input. + * Options that are specific to Date inputs. */ options?: DateInputOptions; } export interface FileInputOptions extends WithEmptyTypeText, WithPaths { /** - * Restricts which file types are available to select or upload to this input. + * Restricts which file types are available to select or upload to this input. Accepted format is + * an array or comma-separated string of MIME types. The special value '*' means any type is + * accepted. */ - accepts_mime_types?: MimeType[] | '*'; + accepts_mime_types?: MimeType[] | string; /** * If you have one or more DAMs connected to your site, you can use this key to list which asset * sources can be uploaded to and selected from. @@ -930,17 +918,17 @@ export interface FileInputOptions extends WithEmptyTypeText, WithPaths { export interface FileInput extends BaseInput { type: 'file' | 'document'; /** - * Options that are specific to this `type` of input. + * Options that are specific to File inputs. */ options?: FileInputOptions; } -export interface ImageInputOptions extends FileInputOptions, ImageResizeable {} +export type ImageInputOptions = FileInputOptions & ImageResizeable; export interface ImageInput extends BaseInput { type: 'image'; /** - * Options that are specific to this `type` of input. + * Options that are specific to Image inputs. */ options?: ImageInputOptions; } @@ -1574,7 +1562,7 @@ export interface Structure extends SchemaBase { style?: 'select' | 'modal'; } -export interface StructureValue extends WithPreview, WithPickerPreview, SchemaBase { +export interface StructureValue extends WithPreview, WithPickerPreview, SchemaBase, Cascade { /** * A unique reference value used when referring to this structure value from the Object input's * assigned_structures option. @@ -1627,6 +1615,17 @@ export interface StructureValue extends WithPreview, WithPickerPreview, SchemaBa * The actual value used when items are added after selection. */ value: unknown; + /** + * Provides short descriptive text for editors shown in the Data Editor for expanded values + * matching this Structure value. Has no default. Supports a limited set of Markdown: links, bold, + * italic, subscript, superscript, and inline code elements are allowed. + */ + comment?: string; + /** + * Provides a custom link for documentation for editors shown in the Data Editor for expanded + * values matching this Structure value. Has no default. + */ + documentation?: Documentation; } export type SelectValues = diff --git a/test/cloudcannon.config.yml b/test/cloudcannon.config.yml index f0982c2..d32f63e 100644 --- a/test/cloudcannon.config.yml +++ b/test/cloudcannon.config.yml @@ -49,6 +49,18 @@ collection_groups: - data _inputs: + image: + type: image + options: + accepts_mime_types: image/png,image/jpeg + mime_type: image/webp + images[*]: + type: image + options: + accepts_mime_types: + - image/png + - image/jpeg + mime_type: image/png range: type: range options: