Merge pull request #688 from gethinode/validation

Refine args handling

data/structures/accordion.yml

@@ -6,7 +6,7 @@ arguments:
     type: string
     optional: true
     comment: >-
-      ID of the accordion, defaults to “accordion-n” with a sequential number n.
+      ID of the accordion, defaults to `accordion-n` with a sequential number n.
   always-open:
     type: bool
     optional: true
@@ -15,4 +15,4 @@ arguments:
   class:
     type: string
     optional: true
-    comment: Class attribute of the accordion, e.g. “w-50”.
+    comment: Class attribute of the accordion, e.g. `w-50`.

data/structures/badge.yml

@@ -3,7 +3,7 @@ comment: >-
 arguments:
   title:
     type: string
-    optional: true
+    optional: false
     comment: >-
       Title of the badge.
   class:

data/structures/button.yml

@@ -12,7 +12,7 @@ arguments:
     type: string
     optional: true
     comment: >-
-      Class attribute of the button element, e.g. “p-5”.
+      Class attribute of the button element, e.g. `p-5`.
   color:
     type: select
     optional: true
@@ -48,7 +48,7 @@ arguments:
   id:
     type: string
     optional: true
-    comment: ID of the button, to be used in the DOM.
+    comment: Identifier of the button, to be used in the DOM.
   state:
     type: select
     optional: true
@@ -61,7 +61,7 @@ arguments:
         - active
         - inactive
   size:
-    type: string
+    type: select
     optional: true
     default: md
     comment: Size of the button.
@@ -85,7 +85,12 @@ arguments:
     comment: >-         
       Assistive label for the button or badge. The label is applied
       to the badge instead of the button when a badge has been defined.
-      The default value of the button aria-label is its title.
+      The default value of the button's assistive label is its title.
+  aria-label:
+    type: string
+    optional: true
+    comment: Alias for label.
+    group: shortcode
   tooltip:
     type: string
     optional: true
@@ -108,7 +113,7 @@ arguments:
         - link
         - button
   placement:
-    type: string
+    type: select
     optional: true
     default: top
     comment: Position of the tooltip.
@@ -134,7 +139,7 @@ arguments:
         - first
         - last
   justify:
-    type: string
+    type: select
     optional: true
     default: center
     comment: Justification of the button title and icon.
@@ -149,7 +154,7 @@ arguments:
   toast:
     type: string
     optional: true
-    comment: ID of the toast to display when the button is clicked.
+    comment: Identifier (ID) of the toast to display when the button is clicked.
   clipboard:
     type:
       - string
@@ -174,6 +179,7 @@ arguments:
     comment: >-
       Dictionary of key-value pairs added as custom attributes to the button
       element ('<a>').
+    group: partial
   spacing:
     type: bool
     optional: true

data/structures/card-group.yml

@@ -11,11 +11,11 @@ arguments:
       - '*hugolib.pageForShortcode'
     optional: true
     comment: Context of the current page.
+    group: partial
   title:
     type: string
     optional: true
-    comment: >-
-      Title of the card, replaces the title of the referenced page (if any).
+    comment: Title of the card group.
   gutter:
     type: int
     optional: true
@@ -24,20 +24,24 @@ arguments:
     options:
       min: 0
       max: 5
+    release: v0.19.0
   list:
     type:
       - page.Pages
       - resource.Resources
     optional: true
     comment: Array of pages to be rendered as cards.
+    group: partial
   cards:
     type: string
     optional: true
     comment: String of rendered cards.
+    group: partial
   max:
     type: int
     optional: true
     comment: Maximum number of cards to display.
+    group: partial
   cols:
     type: select
     optional: true
@@ -51,23 +55,27 @@ arguments:
         - "4"
         - "5"
         - "auto"
+    release: v0.19.0
   paginate:
     type: bool
     optional: true
     comment: >-
       Flag indicating if pagination should be added to the card group, if the
       list exceeds the maximum number of cards to display. 
+    group: partial
   href:
     type: string
     optional: true
     comment: >-
-      address for the button or hyperlink. If set, a button is added if the
+      Address for the button or hyperlink. If set, a button is added if the
       list exceeds the maximum number of cards to display.
+    group: partial
   hrefTitle:
     type: string
     optional: true
     comment: >-
       Title of the button or hyperlink as companion to href.
+    group: partial
   separator:
     type: bool
     optional: true

data/structures/card.yml

@@ -108,15 +108,14 @@ arguments:
       - string
       - template.HTML
     optional: true
-    parent: cascade
     comment: >-
       Description of the card.
     group: partial
   loading:
     type: select
     optional: true
-    default: eager
     parent: cascade
+    default: eager
     comment: >-
       Loading behavior of the image. The loading of lazily loaded images is
       deferred until the image is within scrolling range of the viewport. This
@@ -130,7 +129,6 @@ arguments:
   thumbnail:
     type: path
     optional: true
-    parent: cascade
     comment: >-
       Thumbnail image url, displayed on top or the left of the card.
   ratio:
@@ -157,7 +155,6 @@ arguments:
   icon:
     type: string
     optional: true
-    parent: cascade
     comment: >-
       Font Awesome icon, displayed on top or the left of the card.
   orientation:

data/structures/carousel-item.yml

@@ -24,6 +24,7 @@ arguments:
         - 4x3
         - 16x9
         - 21x9
+    group: partial
   portrait:
     type: bool
     optional: true
@@ -32,6 +33,7 @@ arguments:
       Flag to adjust the ratio from landscape to portrait. The image itself
       is not rotated, only the crop area is adjusted. Not applicable to vector
       graphics.
+    group: partial
   loading:
     type: select
     default: eager

data/structures/carousel.yml

@@ -1,14 +1,14 @@
 comment: >-
   Displays a carousel of several responsive images (see the image shortcode for
-  more details). Add inner <img> elements to define individual image slides.
+  more details). Add inner `img` elements to define individual image slides.
 arguments:
   id:
     type: string
     optional: true
     comment: >-
-      ID of the carousel, defaults to `carousel-` with a sequential number.
+      ID of the carousel, defaults to `carousel-n` with a sequential number `n`.
   ratio:
-    type: string
+    type: select
     optional: true
     comment: >-
       Ratio of the images. If set, the images are resized and cropped to match the
@@ -28,11 +28,12 @@ arguments:
       Flag to adjust the ratio from landscape to portrait. The images themselves
       are not rotated, only the crop area is adjusted. Not applicable to vector
       graphics.
+    release: v0.18.3
   class:
     type: string
     optional: true
-    comment: Class attribute of the carousel element, e.g. “w-75”.
+    comment: Class attribute of the carousel element, e.g. `w-75`.
 body:
   type: string
   optional: false
-  comment: Inner <img> elements that define the individual image slides.
+  comment: Inner `img` elements that define the individual image slides.

data/structures/command.yml

@@ -18,7 +18,7 @@ arguments:
     type: select
     optional: true
     default: bash
-    comment: Type of shell
+    comment: Type of shell.
     options:
       values:
         - bash

data/structures/docs.yml

@@ -30,11 +30,15 @@ arguments:
     optional: true
     default: true
     comment: >-
-      If unset, shows the filename only. By default, the full relative path is
-      shown.
+      If unset, shows the filename only. By default, the entire path (relative
+      to the base path) is shown.
   id:
     type: string
     optional: true
     comment: >-
       ID of the collapse panel holding the code snippet, defaults to
       `docs-collapse-n` with a sequential number `n` starting at `1`.
+  class:
+    type: string
+    optional: true
+    comment: Class attribute of the tab control that wraps the docs element.

data/structures/example.yml

@@ -2,11 +2,17 @@ comment: >-
   Display a code example and render a preview of the same input. The shortcode
   accepts the languages supported by Hugo's highlight function.
 arguments:
+  id:
+    type: string
+    optional: true
+    comment: Identifier of the element’s container.
   lang:
     type: string
     optional: true
     default: markdown
-    comment: Language used to display the code.
+    comment: >-
+      Language used to display the code. Use `hugo` to process Hugo (escaped)
+      shortcodes.
   show_markup:
     type: bool
     optional: true

data/structures/file.yml

@@ -21,19 +21,20 @@ arguments:
     comment: >-
       If unset, shows the panel with the code in collapsed state. By default,
       the panel is expanded.
-  full: 
-    type: string
+  full:
+    type: bool
     optional: true
+    default: true
     comment: >-
-      If unset, shows the filename only. By default, the full relative path is
-      shown.
+      If unset, shows the filename only. By default, the entire path (relative
+      to the base path) is shown.
   id: 
     type: string
     optional: true
     comment: >- 
-      ID of the collapse panel, defaults to `file-collapse-n` with a sequential
-      number `n` starting at 1.
+      Identifier of the collapse panel, defaults to `file-collapse-n` with a
+      sequential number `n` starting at 1.
   class:
     type: string
     optional: true
-    comment: Class argument of the tab control.
+    comment: Class attribute of the tab control that wraps the file element.

data/structures/image.yml

@@ -21,7 +21,10 @@ arguments:
   url:
     type: string
     optional: true
-    comment: Path or url of the image, e.g. `img/example.jpg`.
+    comment: >-
+      Path or url of the image, e.g. `img/example.jpg`. Images with multiple
+      color modes are expected to have a basename that ends with either `-dark`
+      or `-light`.
   src:
     type: string
     optional: true
@@ -39,9 +42,12 @@ arguments:
     type: bool
     default: false
     optional: true
-    comment: Flag indicating if the image should support color modes.
+    comment: >-
+      Flag indicating if the image should support color modes. If set, the
+      shortcode searches for images that having a matching color-mode suffix
+      such as `-light` or `-dark`.
   ratio:
-    type: string
+    type: select
     optional: true
     comment: >-
       Ratio of the image. If set, the image is resized and cropped to match the
@@ -62,6 +68,7 @@ arguments:
       Flag to adjust the ratio from landscape to portrait. The image itself is
       not rotated, only the crop area is adjusted. Not applicable to vector
       graphics.
+    release: v0.18.3
   loading:
     type: select
     default: eager
@@ -75,6 +82,7 @@ arguments:
       values:
         - eager
         - lazy
+    release: v0.21.0
   priority:
     type: select
     default: auto
@@ -102,6 +110,7 @@ arguments:
     type: string
     optional: true
     comment: Class attributes of the wrapper element, e.g. `mx-auto`.
+    release: v0.18.3
   class:
     type: string
     optional: true

data/structures/link.yml

@@ -25,8 +25,8 @@ arguments:
     position: 0
     optional: true
     comment: >-
-       Reference to either an external link (if it starts with http), a named
-       link (if it can be found in params.links), or internal reference.
+       Reference to either an external link (if it starts with `http`), a named
+       link (if it can be found in `params.links`), or internal reference.
        Both external and internal references may include an anchor `#`.
   name:
     type: string

data/structures/mark.yml

@@ -9,7 +9,7 @@ arguments:
     optional: true
     comment: >-
       Theme color of the highlight. By default, the highlight uses the color of
-      the HTML mark function.
+      the HTML mark function (usually yellow).
     options:
       values:
         - primary