mightymite/README.md

# Mightymite
A tiny (yet mighty) markdown-based content store and API.

- [Why?](#why?)
- [How it works](#how-it-works)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#config)
- [Import syntax](#import-syntax)
- [Data files](#data-files)
- [Routes file](#routes-file)

## Why?
I needed a dead-simple database-less API for accessing content written in markdown with YAML front-matter, that also handles the compilation into JSON and parsing of markdown into HTML. The file-based nature of the API lends itself to hosting anywhere static files may be hosted.

## How it works
Content is organized as `index.md` files within `/content`, in a hierarchy of directories that will map to the client application routes. Each file is parsed as YAML/markdown, with the body compiled as HTML, and output as JSON to `/api`.

To avoid unnecessary imports on the client side, documents may import certain collections of other files at compilation time using an [import syntax](#import-syntax). For instance, you may want to include a limited set of attributes from the latest _n_ blog posts on the home page.

Beyond that, any front-mattter attributes will be available under `attributes`, and the body HTML will be available at `body`.

## Installation
```sh
$ yarn add mightymite # or npm install mightymite
```

## Usage
```sh
# View commands and options
$ mightymite --help

# Build
$ mightymite build

# Rebuild on file change
$ mightymite watch

# Specify source or output directories other than the defaults
$ mightymite build --src src --out dist
$ mightymite watch --src src --out dist
```

## Configuration
You may use a custom config file by passing along the `config` flag:

```sh
$ mightymite build --config mightymite.json
```

And in `mightymite.json`:
```json
{
  "debug": "true",
  "src": "src",
  "out": "dist"
}
```

## Import syntax
Content from additional files may be imported using the `import` attribute:

```yaml
# /content/index.md
title: Home

_import:
  posts:
    match:
      - 'news/**/index.md'
      - '!news/index.md'
    order: date
    sort: desc
    limit: 5
    body: true
    attributes:
      - title
      - date
```

## Data files
Any `.yaml` files within the content directory will be converted to JSON and moved to their corresponding location in the output directory. [Imports](#import-syntax) are supported.

```yaml
# /data.yaml

title: My Site

# Let's import the description from the about page
_import:
  about:
    match: '/about/index.md'
    attributes:
      - description
```

## Routes file
A register of all routes are published to the output directory in `routes.json`.