1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
---
title: Hello, World!
date: 2014-06-22
route: /hello-world
hidden: true
---
Tinman is a tiny static-ready blog engine based on the
[toto](http://github.com/cloudhead/toto) library.
```
npm install -g tinman
```
## What is Tinman?
A basic tinman blog looks like this:
```
example
├── articles
│ └── 2014-06-22-hello-world.md
└── public
└── style.css
```
Some features include:
- Generate a simple blog with nothing but a few markdown files
- Serve anything static by placing it in the _public/_ directory
- A comprehensive CLI to handle best-practices for you
- Customize templates to your heart's desire
- Run your blog as web server or export it as a static site
- Add any CSS or JavaScript and have it just work
#### What do I get?
Tinman generates a page for each article, and an index page listing your
articles (sorted by filename). Naming your articles `YYYY-MM-DD-my-title.md`
will sort them such that the most recent article is listed first. It
will also set the article's date property for you.
## Usage
#### Create a new blog
```bash
$ tinman create
Blog title: myblog
Your blog is ready! To get started:
cd myblog/
tinman server
$ tinman create myblog
# Generate example templates to play with as well
$ tinman create myblog --with-templates
```
#### Generate a new article
```bash
$ tinman new
Title: This is my first blog post
Article generated at: articles/2014-07-05-this-is-my-first-blog-post.md
```
#### Run your blog on a local webserver
```bash
$ tinman server
Server listening on port 3000...
$ tinman server --port 1337
Server listening on port 1337...
```
#### Build your blog as a static site
```bash
$ tinman build
Blog successfully built to: build/
$ tinman build --output-dir www
Blog successfully built to: www
```
## Writing Articles
Articles are written in [Markdown](http://daringfireball.net/projects/markdown/)
and use YAML Front Matter to set various options.
```markdown
---
title: Hello, World!
date: 2014-06-22
---
Once upon a time...
```
This article will be accessible at the url `/hello-world` by default
(based on the article's title). You can customize this option by either:
- Setting the `slug` property, making the article accessible at
`/your-slug-here`
- Setting the `route` property, and completely overriding the slug (i.e.
`route: /2014/06/24/musings/my-article`)
You can include any custom options you'd like (i.e. `color: red`) in
your YAML Front Matter, and recall it from a custom template.
## Templates
Tinman uses [EJS](http://embeddedjs.com/) templates and includes the
following:
- **article.ejs** for templating an individual article
- **index.ejs** for the article index page
- **layout.ejs** which wraps around the other two and renders asset tags
To customize these templates, pass the `--with-templates` option to
`tinman create`:
```bash
$ tinman create myblog --with-templates
Your blog is ready! To get started:
cd myblog/
tinman server
$ tree myblog
myblog
├── articles
│ └── 2014-06-22-hello-world.md
├── public
│ └── style.css
├── templates
│ ├── article.ejs
│ ├── index.ejs
│ └── layout.ejs
└── tinman.json
```
Beyond the articles directory and sample stylesheet, the
`--with-templates` option creates a templates directory and a
`tinman.json` file, instructing Tinman to use these templates instead of the
ones built into it.
#### What Data Do My Templates Receive?
The **article template** receives all properties of the article as defined in
the YAML Front Matter. The content of the article is stored as `body`. Some
extra fields include:
- **summary**: the first paragraph of the rendered article
- **filename**: self-explanatory
- **date**: the date either extracted from the filename or from the
`date` property of the article's Front Matter
The **index template** has access to the array `articles`, which holds
every article in your blog.
The **layout template** receives the blog's title and a `body`, which
contains the rendered HTML of the page it contains (either an article
page or the index). This template also has access to two strings,
`stylesheets` and `scripts`, which store the CSS/JS resource tags
generated automatically based on the contents of your public directory.
## Static Files
Tinman will automatically copy static assets (images, stylesheets,
javascripts) from the "public" directory (default: `public/`).
For instance, you can write the following to **public/css/colors/main.css**:
```css
body {
color: #222222;
}
```
And access it like so:
```html
<link rel="stylesheet" href="/css/colors/main.css" />
```
You can follow the same pattern for including images in your articles,
or even serving static HTML documents.
In addition, Tinman scans for javascripts (`*.js`) and stylesheets (`*.css`)
and automatically generates resource tags which are placed in the layout
template (_layout.ejs_ is sent both a _scripts_ and _stylesheets_
string). **You do not need to edit any templates after writing
javascripts or stylesheets.**
[MIT Licensed](https://github.com/jdan/tinman/blob/master/LICENSE)
|