Customizing Skele

Skele is designed to be customized to suit your needs. This guide covers the basics of customizing Skele to make it your own.

What's Inside?

This guide covers customizing Skele for your needs:

1. Explore the Structure

Get familiar with the file structure of a Skele site.

2. Edit an Existing Component

Extend the functionality of a component.

3. Create a New Component

Design and build a component from the ground up.

1a. Explore the File Structure

Let's explore the structure of a Skele site:

_component-library - the source code for the components.
_esbuild - the JavaScript for components, the site, and the Skele Component Library.
_icons - SVG icons that can be referenced by file path (without the .svg extension) in any icon element.
_liquid - Various liquid shortcodes and filters used across the components, site, and Skele Component Library.
_sass - the CSS for components, the site, and the Skele Component Library.
.cloudcannon - files to help Skele work seamlessly with CloudCannon.
site - An 11ty site that's the actual website.
skele - An 11ty site that's the Skele Component Library.

1b. Explore the Component Structure

Components live in _components and are powered by Bookshop to enable live editing on CloudCannon.

There are two types of components, elements and layouts. Elements are simple, smaller components like buttons and headings, while layouts define the page structure and can contain many elements.

1c. Explore the CSS Structure

CSS is managed in the _sass and is built with Sass:

skele.scss: The main CSS file contains all component and page styles. Component-specific styles are organized in the components/ directory, mirroring the _components structure. You can customize variables for colors, spacing, and widths in _variables.scss, as well as tweak the light and dark themes in themes/_theme-light.scss and themes/_theme-dark.scss.
library.scss: Handles the styling for the Skele Component Library.
prism.scss: Provides syntax highlighting for code blocks and is automatically included on pages with code snippets.

1d. Explore the JavaScript Structure

JavaScript is managed in _esbuild and is built with esbuild:

skele.js: The main JS file, containing all component and page scripts. Component-specific styles are organized in the components/ directory, mirroring the _components structure.
library.js: Contains the scripts for the Skele Component Library.
prism.scss: Provides syntax highlighting for code blocks and is automatically included on pages with code snippets.

2. Edit an Existing Component

To demonstrate how to edit an existing component, we'll customize the button component to add the ability to change the border type between solid, dashed, and dotted.

Add a section to button component (_component-library/components/elements/button.eleventy.liquid) to add a class if border_type is passed:
```
{% if border_type %}
  {% assign extra_classes = extra_classes | append: ' button--' | append: border_type %}
{% endif %}
```
Add the new field and options to the component bookshop configuration (_component-library/components/elements/button.bookshop.yml) so CloudCannon
can render the new field with the correct options in the editor:
```
blueprint:
  border_type:
  ...

_inputs:
  border_type:
    comment: The type of border
    type: select
      options:
        values:
          - solid
          - dotted
          - dashed
  ...
```

Add new CSS classes to _sass/components/elements/_button.scss:

&--solid {
  border-style: solid;
}

&--dotted {
  border-style: dotted;
}

&--dashed {
  border-style: dashed;
}

Document the new button feature in the Skele Component Library (skele/src/collections/components/elements/button.md):

property_descriptions:
  - name: border_type
    type: enum
    enum_options: 
      - name: solid
        description: Shows the button with a solid border
      - name: dotted
        description: Shows the button with a dotted border
      - name: dashed
        description: Shows the button with a dashed border
    description:  The type of border for the button
    default: solid
    children:
 ...

Add an example of usage in the (skele/src/collections/examples/elements/buttons/border-type.html).

---
name: Border Type
frontmatter_fields:
  - block
block:
  _bookshop_name: layouts/button-group
  button_blocks:
    - _bookshop_name: elements/button
      border_type: solid
      label: Solid
      link:
      icon:
        display_mode:
        position:
        name:
      layout: 
      size: 
      type: primary
      outline: true
    -   _bookshop_name: elements/button
        border_type: dotted
        label: Dotted
        link:
        icon:
          display_mode:
          position:
          name:
        layout: 
        size: 
        type: primary
        outline: true
    - _bookshop_name: elements/button
      border_type: dashed
      label: Dashed
      link:
      icon:
        display_mode:
        position:
        name:
      layout: 
      size:
      type: primary
      outline: true
  options:
    direction: row
    align: start
    gap: s
    margin:
      top: null
      bottom: null
---
{% bookshop "{{block._bookshop_name}}" bind: block %}

Add the example to the Button component documentation (skele/src/collections/components/elements/button.md):

examples:
  - name: Border Type
    slug: border-type
    description:
    size: s
  ...

All done. (optional) update existing button components to have the border_type field.

3. Create a New Component

Creating a new component is similar to our steps for editing an existing component:

Create a new folder in _components/components/elements|layouts for your component. Create a new .eleventy.liquid file in the new folder with the HTML and liquid for your component. Create a new .bookshop.yml file in the new folder with the configuration for your component.
Create a new .scss file in _sass/components/elements|layouts with your component's styles. Reference your newly created .scss file in the _index.scss file in the same folder.
If your component requires JavaScript, create a new .js file in _esbuild/components/elements|layouts with your component's scripts. Reference your newly created .js file in the skele.js file.
Document your new component in the Skele Component Library by creating a markdown file in skele/src/collections/components/elements|layouts. Create examples
for your component in the skele/src/collections/examples/elements|layouts folder.
Start using your new component on your site.