Skip to content

arestivo/sitory

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Sitory

Sitory is a dead-simple static website generator written in TypeScript using Marked and handlebars.

Installing

Just run:

yarn global add sitory

Or, if you prefer npm:

npm install -g sitory

Quick Start

Just run the following commands:

sitory init <path>
cd <path>
sitory build
sitory serve

This 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:5000

How 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.

  1. All files in assets are copied directly to public.
  2. Files in content are also copied to public, except if they are markdown (.md) files.
  3. Markdown files in content are transformed into html files and copied to public. If the file is called index.md, then sitory will copy the corresponding index.html file to the same folder in public, otherwise sitory will create a new folder with the same name as the file. This allows accessing a file called info.md in the browser at info/ instead of info.html.
  4. When creating an HTML file, sitory will use a handlebars template present in the layouts/pages folder. By default, this template will be called default.hbs but this can be changed for a particular folder or file.
  5. 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.
  6. You can create variables in three different places; in a root config.yaml file, in a config.yaml inside any folder in content, 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 as data.name.
  7. 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 /).
  1. You can have yaml files in the data folder 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

  1. Set the title variable in /config.yaml to 'Sitory Example':
title: Sitory Example
  1. Create content/books/config.yaml:
title: Sitory Example | Books

Now, inside the books folder, all pages will receive this updated title variable.

  1. Replace the generated /content/index.md with:
[books](books)
  1. Replace the generated /layouts/pages/default.hbs so that it uses the title variable:
<!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>
  1. 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
  1. Create a new page at /content/books/index.md with:
---
template: book-list
books: =books.yaml=
---
These are some of my books:
  1. Create a new /layouts/pages/book-list.hbs that 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>
  1. Create a new partial at layouts/partials/book.hbs with:
<li>{{book.title}} by {{book.author}} ({{book.year}})</li>
  1. Now, lets call this partial from the book-list template. Replace the each loop with:
{{#each data.books}}{{>book book=this}}{{/each}}
  1. Create another partial at layouts/partials/head.hbs with:
<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>
  1. Replace this code in both page layouts with a call to the partial:
{{>head}}
  1. Finally, adjust assets/css/style.css to your liking!

About

A dead simple static content generator

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published