Sitory
Sitory is a dead-simple static website generator written in TypeScript using Marked and handlebars.
Installing
Just run:
yarn global add sitoryOr, if you prefer npm:
npm install -g sitoryQuick Start
Just run the following commands:
sitory init <path>
cd <path>
sitory build
sitory serveThis will create a new folder called path, initialize a default sitory website inside that folder, and serve it at the default port 3000.
Then open http://localhost:3000 to see your brand new sitory website.
Usage
sitory <command>
Commands:
sitory init [path] initialize a sitory site in the current directory
sitory build [-c config] build the site
sitory serve [-p port] start a webserver serving the site
Options:
--version Show version number [boolean]
--help Show help [boolean]
Examples:
sitory init Initialize a sitori website at the current directory
sitory build Build the sitori website at the current directory
sitory serve Serve the website at http://localhost:3000
sitory serve -p 5000 Serve the website at http://localhost:5000How does it Work
When you run sitory build in a folder with a sitory project, sitory will generate a static website in the public folder inside that path.
- All files in
assetsare copied directly topublic. - Files in
contentare also copied topublic, except if they are markdown (.md) files. - Markdown files in
contentare transformed intohtmlfiles and copied topublic. If the file is calledindex.md, thensitorywill copy the correspondingindex.htmlfile to the same folder inpublic, otherwisesitorywill create a new folder with the same name as the file. This allows accessing a file calledinfo.mdin the browser atinfo/instead ofinfo.html. - When creating an HTML file, sitory will use a handlebars template present in the
layouts/pagesfolder. By default, this template will be calleddefault.hbsbut this can be changed for a particular folder or file. - Both page layout files and markdown files can use handlebars partials stored inside
layouts/partials. Use this to create parts of your layouts that are repeated (e.g., a header) or small HTML snippets that you can call from your markdown content. You can also pass variables to your partial files. - You can create variables in three different places; in a root
config.yamlfile, in aconfig.yamlinside any folder incontent, or in the preamble of any markdown file. Variables will propagate and be replaced, starting from the root config file, each folder's config file, and finally the variables in the preamble. These variables can be used in layouts and partials asdata.name. - Some variables have special meanings:
- template: is the template's name to be used (default is default).
- baseURL: is the base URL of the generated site (default is /).
- You can have yaml files in the
datafolder that can be read into a variable using the special syntax=<filename>=(The<and>are not part of it). These can be read anywhere a variable can be set.
A Complete Example
- Set the
titlevariable in/config.yamlto 'Sitory Example':
title: Sitory Example- Create
content/books/config.yaml:
title: Sitory Example | BooksNow, inside the books folder, all pages will receive this updated title variable.
- Replace the generated /content/index.md with:
[books](books)- Replace the generated
/layouts/pages/default.hbsso that it uses thetitlevariable:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="{{ data.baseUrl }}css/style.css">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ data.title }}</title>
</head>
<body>
<a href="{{ data.baseUrl }}"><h1>{{ data.title }}</h1></a>
{{{ content }}}
</body>
</html>- Create a data file in
data/books.yaml:
- title: Dune
author: Frank Herbert
year: 1965
- title: Do androids dream of electic sheep?
author: Philip K. Dick
year: 1968- Create a new page at
/content/books/index.mdwith:
---
template: book-list
books: =books.yaml=
---
These are some of my books:- Create a new
/layouts/pages/book-list.hbsthat can display a list of books:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="{{ data.baseUrl }}css/style.css">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ data.title }}</title>
</head>
<body>
<a href="{{ data.baseUrl }}"><h1>{{ data.title }}</h1></a>
{{{ content }}}
<ul>
{{#each data.books}}{{>book book=this}}{{/each}}
</ul>
</body>
</html>- Create a new partial at
layouts/partials/book.hbswith:
<li>{{book.title}} by {{book.author}} ({{book.year}})</li>- Now, lets call this partial from the book-list template. Replace the
eachloop with:
{{#each data.books}}{{>book book=this}}{{/each}}- Create another partial at
layouts/partials/head.hbswith:
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="{{ data.baseUrl }}css/style.css">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ data.title }}</title>
</head>- Replace this code in both page layouts with a call to the partial:
{{>head}}- Finally, adjust
assets/css/style.cssto your liking!