datasite
v0.6.0
Published
Easily generate data-driven static sites.
Downloads
43
Readme
datasite
Easily generate data-driven static sites.
Usage
Step 1: Set up a project
Start by initializing an NPM project:
npm init
# Follow the interactive prompts...
Next, add datasite
as a dependency, and http-server
as a development dependency:
npm install --save datasite
npm install --save-dev http-server
Add scripts to build your site and serve it locally:
{
"name": "my-cool-datasite",
"scripts": {
"start": "npm run build && npm run serve",
"build": "datasite --config ./datasite.config.js",
"serve": "http-server -p 3500 build/"
},
"dependencies": {
"datasite": "^0.4.1"
},
"devDependencies": {
"http-server": "^0.12.0"
}
}
Create a file named datasite.config.js
, and add this content to start:
const SITE_DESCRIPTION = `
This is my cool Datasite.
Thank you for visiting!
## Datasite Features
- Easy configuration of datasets and dashboards
- Quick filtering
- Markdown support on site/dashboard descriptions (**bold**, _italics_, [links](https://www.youtube.com/watch?v=dQw4w9WgXcQ), etc.)
- And more!
`;
module.exports = {
general: {
title: 'My Cool Datasite',
description: SITE_DESCRIPTION
},
datasets: [
// Define datasets here
],
dashboards: [
// Define dashboards here
]
};
This will configure a datasite with no data yet, but with a Markdown-supported home page.
Run this script to build and serve your datasite:
npm start
Point your browser to http://localhost:3500 and you will see your new datasite!
Step 2: Add data
Each dataset is a normalized list of headers and rows, ready to display in a table.
Datasets are generated from raw input files at build time.
Create an input file:
mkdir data
touch data/example-raw-data.json
And paste in some contents:
{
"data": [
["blue", "triangle", 87, false],
["red", "triangle", 60, true],
["blue", "square", 79, false],
["red", "circle", 65, false],
["green", "circle", 43, true]
]
}
Now, define a dataset that will transform this data into something that Datasite will understand:
datasite.config.js
// ...
module.exports = {
general: {
title: 'My Cool Datasite',
description: SITE_DESCRIPTION
},
datasets: [
// Define datasets here
{
id: 'EXAMPLE_DATASET',
inputFile: './data/example-raw-data.json',
headers: [
{
id: 'color',
title: 'Color'
},
{
id: 'shape',
title: 'Shape'
},
{
id: 'size',
title: 'Size'
},
{
id: 'deluxe',
title: 'Deluxe?'
}
],
inputToRows: (dataset) => {
return dataset.data
.map(inputRow => {
const [color, shape, size, deluxe] = inputRow;
// Each row is an object, containing keys that match `headers` above
return {
color,
shape,
size,
deluxe
};
});
}
}
],
dashboards: [
// Define dashboards here
]
};
Datasets are referenced by dashboards, which also contain metadata like a title and description.
Define a dashboard:
datasite.config.js
// ...
const EXAMPLE_DASHBOARD_DESCRIPTION = `
This shows data about a lot of shapes.
Read *all* about it.
`;
module.exports = {
// ...
dashboards: [
// Define dashboards here
{
dataset: 'SHAPES',
title: 'Data about Shapes',
// Sets the URL for the dashboard
slug: 'data-about-shapes',
description: EXAMPLE_DASHBOARD_DESCRIPTION,
filters: []
}
]
};
Restart the script to build and serve your datasite:
npm start
And refresh your browser. Now there is a dashboard on the site!
Step 3: Refactor as your datasite grows
Now that you know how to create datasets and dashboards, you can replace the examples with real content. As you add more data to your site, you may want to create new directories and files to organize everything. Then reference them from your config file.
Since Datasite acts on raw data files and converts them into normalized datasets, you will likely want to create bash scripts to generate or update these files.
Here is an example of how to organize a datasite:
my-project/
config/
datasets/
animals.js
people.js
content/
dashboards/
animals.md
people.md
home.md
data/
raw-animal-data.json
raw-people-data.json
scripts/
generate-animal-data.sh
generate-people-data.sh
datasite.config.js
package.json