CampKit

CampKit is a source generation and scaffolding tool.

Quick Look

1. Create a layout

version: 1
name: MyLayout
description: 'Some description'
structure:
  src/components: {}
  readme.md: {}

2. Create a project

mkdir my-project
cd my-project
touch Campfile.yml

Campfile.yml:

version: 1
name: MyProject
description: 'Some description'
layout: MyLayout
args: {}

3. Generate the project

camp build

Concepts

CampKit is built around the idea of generating code from structure description files.

The Campfile

The Campfile is a YAML file that describes the main layout and its contents in a project.

version: 1
name: Example
description: "This is an example project."

settings: # declare global variables (used by every rendering context)
  aCustomValue: Anything

layout: <layout name> # main layout for this project
args: # arguments for layout params
  <layoutParam>: <layout param value>
contents: # define contents fot layout slots
  <layout slot>: # named slot from layout
    <content key>: # named slot content
      args: # args for slot params
        <slot param name>: <some value>

sources: # import layouts (at least the main one used in the Campfile)
  <layout name>:
    local: <path/to/layout/dir>

Layouts

A CampKit layout is a YAML file that describes the structure of a directory tree and optional slots for additional nested structures. Layouts are used as templates to generate the defined structure according to the provided arguments.

Camp looks for layout.yml files in the root of a referenced source directory (sources in Campfiles or use in layouts).

version: 1
name: <layout name>
description: 'Some description'

params: # layout params
  <param name>:
    type: string # string, number, boolean
    description: 'Param description'
    required: true # optional: false by default

use: # import layouts used by this layout
  <layout name>:
    local: <path/to/layout/dir>

slots: # declare slots for contexts
  <slot name>:
    # declare destination for generated sub-structure
    structureTarget: 'notes/{title}/' # use slot params to build dynamic content paths
    slotParams: # define slot params
      title: # some slot param name (can be anything)
        type: string # string, number, boolean
        description: 'Skit param description'
        required: true # optional: false by default
    generate: # define layouts to be generated in this slot (can be multiple)
      note: # use the layout name to generate substructure
        args: # pass args defined in the generator layout params
          title: '{title}.note' # substitute args from slot params
          <param name>: 'static value'

# define static filesystem structure
structure:
  notes/: {} # mark directories with trailing slash
  .gitignore: {} # any other entry is considered a file
  docs/README.md: {} # nested files can be defined like this

layouts: # declare inline layouts used by this file
  note: # layout name
    description: 'A note layout'
    params: # layout params
      title: # param name
        type: string
        description: 'Note title'
        required: true
      <param name>: # param name
        type: string
        description: 'Some param'
        required: false
    structure: # layout structure
      '{title}.md': {}

Structure

Layout structures can define directories and files. The structure may contain nested paths.

Directories are marked with a trailing slash. Any other entry is considered a file.

Params

Layouts can define input parameters that can be used to generate the layout structure. Params can define types, descriptions and whether they are required.

Slots

Slots are used to mark directories from the static structure as places for generate additional nested contents.

Slots should define a structureTarget that defines the path to the generated contents and a generate section that defines layouts to be used to generate the contents.

Slots can define input parameters that can be used to generate the slot content paths and as arguments for the generator layouts.

Templates

You can define file generators in the structure/ directory next to the layout file.

structure:
  '{title}.md': {}
  .gitignore: {}
  docs/readme.md: {}

The files should be js files named after the file entry they generate.

.

├── layout.yml
└── structure/
    ├── {title}.md.js
    ├── .gitignore.js
    └── docs/
        └── readme.md.js

And the files should export a function that takes a context object as an argument and returns a string.

For {title}.md.js:

export default (context) => `
# ${context.args.title}
`

Note: if a file generator is not defined in the layout structure, it will be ignored and the generated file will have empty content.

Slotfiles

Slotfiles are YAML files that describe the contents of a layout slot.

During structure building, CampKit will look for slotfiles in the slot directories and generate the contents according to the slot layouts.

name: <slot name>
description: 'slot description'
layout: <layout name> # layout used to generate slot contents

contents: # slot map
  <slot name>: # from the layout
    <content key>: # any name
      args: # args for the generator layout params
        <some param name>: 'some value'