Skip to content

A simple API for delivering content from static files and folders.

License

Notifications You must be signed in to change notification settings

gavinmcfarland/stancy

Repository files navigation

Stancy

npm

Stancy uses static files and folders to generate a database of collections and items. The database can be queried as a plain object, outputted as a json file, or served using an express server for a RESTlike API. This is useful for building static sites which use frameworks like React, Vue, Svelte or Marko. Stancy is unbiased about how you use it and can be customised to suit different use-cases.

Example

In this example, we'll look at how we can create a database from static files and folders which can be accessed using an API for a website.

Start by creating a folder with some content, below is an example. Each top level file or folder creates a root endpoint.

content/
  site.json
  pages/
    home.md
    about.md
    services.md

Here we've created a file site.json which stores key information about our site, some pages, and a blog.

Now start the server.

stancy('content/').server(3000, '/api/')

We can access the content using the following requests:

Check out the examples.

Installation

Add the npm package to your project.

npm install stancy

Features

  • Server and client

    Easily serve content from static folders and files, and fetch content.


  • Collections and Items

    Collections are created by plural sounding folders. Items are created using files and non-plural sounding folders.


  • Preprocess data

    Easily sort collections, format dates, and parse content on the client.


  • Index File

    This is useful if you prefer to organise using folders or if you want to create an index page for a group of related content.

    # Creates a collection of items
    posts/
      item-one.md
      item-two.md
      item-three.md
    
    # Creates an item
    item/
      index.md

  • Hidden

    Prepend an underscore to hide a file or folder. In the case of hiding a folder, this will also hide all it's contents.

    _file-is-hidden.md
    _folder-is-hidden/
    

  • File Types (Planned)

    The following file types are supported.

    • Archives
    • Audio
    • Code
    • Documents
    • Images
    • Videos

  • Meta Data (Planned)

    You can add meta data to images by creating a data file with a matching name.

    my-first-post/
      playing-frisbee.jpg
      playing-frisbee.yml
    

    This will create the following image meta data

    {
      // ...
      "images": [
        {
          "src": "/static/playing-frisbee.jpg",
          "alt": "Me playing frisbee"
        }
      ]
    }

  • Built in Fields

    If you create a database you can filter and show data using a query language of your choice using the following field names.

    Private

    • _name Name of the resource
    • _collection Collection the resource belongs to
    • _index The index of the resource in the collection or dataset
    • _type The type of resource. Named after the folder or file.
    • _source The path to the folder containing the file.

    Public

    • url The url to the resource.

Docs

  • Starting a server

    stancy(source).server([port, path])

    Arguments

    • source { String } source of the content directory to be servered
    • port { Number }
    • path { String } subpath where API will be accessible from

    Example

    stancy('content/').server(3000, '/api/')

  • Starting a client

    stancy([source]).client(url)

    Arguments

    • url { String } url of the production server

    Example

    stancy('content/').client('http://domain.com/api/')

  • Preprocessing data

    client.preprocess([type,] callback)

    Useful for sorting collections, formatting dates, or parsing markdown.

    Arguments

    • type { String } can be one of the following:
      • collection returns every collection as an array of objects.
      • item returns every item as an object with key value pairs.
      • content returns value of every item with a property of content.
    • callback { function } gives access to one of the types of data above.

    Examples

    An example of sorting collections by date

    client.preprocess('collection', (data) => {
        return data.sort((a, b) => {
            if (a.date > b.date) {
                return 1;
            } else if (a.date < b.date) {
                return -1
            } else {
                return 0
            }
        })
    })

    An example of formatting machine readable dates

    client.preprocess('item', (data) => {
        return data.date = new Date(data.date)
    })

    An example of parsing markdown

    client.preprocess('content', (data) => {
        return marked(data)
    })

  • Getting data

    client.get('users/jerry').then(res => {
        console.log(res)
    }).catch(err => { 
        console.log(err)
    })

    Example response

    {
        "url": "users/jerry",
        "name": "Jerry",
        "age": "24",
        "role": "admin",
        "content": "<h1>Jerry</h1>"
    }

  • Creating a database

    stancy(source).database()

    Example

    var database = stancy('content/').database()

  • Configure using config file (Planned)

    stancy.config.js

    {
        source: 'content/',
        client: {
            production: 'https://stancy.now.sh/api/',
            token: 'T89ALS90',
            preprocess: ({content}) => {
                content = marked(content)
            }
        }
    }

    Specify custom config file

    stancy().config('src/stancy.config.js')

Development

To install the dependencies

npm install

To run the demo server

npm run demo

To run tests

npm run test