lunyav.tngl.sh
forked from
starlightnet.work/Makko
Makko, the people-oriented static site generator made for blogging.
Fixed indentation
+132
-146
+132
-146
doc/blog/english.md
+132
-146
doc/blog/english.md
···
40
40
The `makko.json` file will look something like this by default:
41
41
```json
42
42
{
43
-
"title": "My Makko blog!",
44
-
"url": "https://yourweb.site",
45
-
"description": "My very own blog made with Makko!",
46
-
"paths": {
47
-
"symlinks_enabled": false,
48
-
"source": "blog/",
49
-
"output": "web/",
50
-
"templates": "templates/"
51
-
},
52
-
"feeds": {
53
-
"html": "index.html",
54
-
"rss": "feed.rss",
55
-
"atom": "feed.atom"
56
-
},
57
-
"custom": {
58
-
"hey1": "You can add anything here, then reference it in your templates",
59
-
"hey2": "or markdown files like this: {{custom.hey1}}, {{custom.hey2}}",
60
-
"note": "Any JSON input through STDIN will be overlaid on top of this."
61
-
},
62
-
"callbacks": {
63
-
"on_change": null,
64
-
"on_create": null,
65
-
"on_delete": null,
66
-
"on_modify": null
67
-
},
43
+
"title": "My Makko blog!",
44
+
"url": "https://yourweb.site",
45
+
"description": "My very own blog made with Makko!",
46
+
"paths": {
47
+
"symlinks_enabled": false,
48
+
"source": "blog/",
49
+
"output": "web/",
50
+
"templates": "templates/"
51
+
},
52
+
"feeds": {
53
+
"html": "index.html",
54
+
"rss": "feed.rss",
55
+
"atom": "feed.atom"
56
+
},
57
+
"custom": {
58
+
"hey1": "You can add anything here, then reference it in your templates",
59
+
"hey2": "or markdown files like this: {{custom.hey1}}, {{custom.hey2}}",
60
+
"note": "Any JSON input through STDIN will be overlaid on top of this."
61
+
},
62
+
"callbacks": {
63
+
"on_change": null,
64
+
"on_create": null,
65
+
"on_delete": null,
66
+
"on_modify": null
67
+
},
68
68
}
69
69
```
70
70
···
76
76
`makko.json`
77
77
```json
78
78
{
79
-
"title": "the best blog to have ever existed.",
80
-
"url": "https://thebest.blog",
81
-
"description": "that's right!"
82
-
...
79
+
"title": "the best blog to have ever existed.",
80
+
"url": "https://thebest.blog",
81
+
"description": "that's right!"
82
+
...
83
83
```
84
84
85
85
`templates/feed.html`
86
86
```html
87
-
<!doctype html>
88
-
<html lang="en">
89
-
<head>
90
-
<title>{{website.title}}</title>
91
-
</head>
92
-
<body>
93
-
<h1>{{website.title}}</h1>
94
-
<p1 style="opacity: 60%">{{website.description}}</p1>
95
-
...
96
-
</body>
97
-
</html>
87
+
<head>
88
+
<title>{{website.title}}</title>
89
+
</head>
90
+
<body>
91
+
<h1>{{website.title}}</h1>
92
+
<p1 style="opacity: 60%">{{website.description}}</p1>
93
+
...
94
+
</body>
98
95
```
99
96
100
97
You get:
···
114
111
115
112
To better understand how to use templates in Makko, it is recommended you take a look at the [official Mustache tutorial](https://mustache.github.io/mustache.5.html). We also recommend looking at the [Template data reference](#template-data-reference) to see all the `{{different.data}}` you can use.
116
113
117
-
> **Note:** You actually do not require `url` to be valid if you're only targetting HTML, It is mostly used for Atom and RSS data as they need a way to point users to individual posts in your website. (see the `feeds` section below)
114
+
> **Note:** You actually do not require `url`, `title` or `description` to be valid if you're only targetting HTML, It is mostly used for Atom and RSS as they serve as useful metadata. (see the `feeds` section below)
118
115
119
116
120
117
## `paths`
···
139
136
- `rss`: An RSS feed, which allows people to "subscribe" to your website and be up-to-date with new posts as long as they have a RSS reader.
140
137
- `atom`: Similar to RSS but more modern and better defined.
141
138
142
-
To disable any of these, you can set its output path to `null`
139
+
To disable any of these, you can set their output path to `null`.
143
140
144
141
145
142
## `custom`
···
147
144
148
145
```json
149
146
"custom": {
150
-
"about_me": {
151
-
"name": "Neil D. Foster",
152
-
"age": 20
153
-
},
154
-
155
-
"awesomeness": 100,
156
-
"love": "❤️"
147
+
"about_me": {
148
+
"name": "Neil D. Foster",
149
+
"age": 20
150
+
},
151
+
152
+
"awesomeness": 100,
153
+
"love": "❤️"
157
154
}
158
155
```
159
156
160
157
`my_post.md`
161
158
```markdown
162
159
{{#custom.about_me}}
163
-
I'm {{name}}!
164
-
I'm exactly {{age}} years old!
160
+
I'm {{name}}!
161
+
I'm exactly {{age}} years old!
165
162
{{/custom.about_me}}
166
163
167
164
The awesomeness rate today is {{custom.awesomeness}}!
···
182
179
`overlay.json`
183
180
```json
184
181
{
185
-
"about_me": {
186
-
"name": "Comet Startling",
187
-
}
188
-
"love": "💥"
182
+
"about_me": {
183
+
"name": "Comet Startling",
184
+
}
185
+
"love": "💥"
189
186
}
190
187
```
191
188
···
213
210
214
211
```json
215
212
[
216
-
{
217
-
"status": "created",
218
-
"id": "WHATEVER000",
219
-
220
-
"source": "cakepie.md",
221
-
"url": "cakepie.html",
222
-
223
-
"title": "wow i love cake and pie!",
224
-
"description": "here's how to make a cake that is also a pie, yeah!",
225
-
"author": "cake pie lover."
226
-
},
227
-
228
-
{
229
-
"status": "modified",
230
-
"id": "SUPERCOOL123",
231
-
232
-
"source": "supercool.md",
233
-
"url": "supercool.html",
213
+
{
214
+
"status": "created",
215
+
"id": "WHATEVER000",
216
+
217
+
"source": "cakepie.md",
218
+
"url": "cakepie.html",
219
+
220
+
"title": "wow i love cake and pie!",
221
+
"description": "here's how to make a cake that is also a pie, yeah!",
222
+
"author": "cake pie lover."
223
+
},
234
224
235
-
"title": "i think superman is supercool",
236
-
"description": "i cried with the new movie.... i cried....",
237
-
"author": "super man lover."
238
-
},
239
-
240
-
{
241
-
"status": "deleted",
242
-
"id": "EMBARRASINGPOST985",
225
+
{
226
+
"status": "modified",
227
+
"id": "SUPERCOOL123",
228
+
229
+
"source": "supercool.md",
230
+
"url": "supercool.html",
231
+
232
+
"title": "i think superman is supercool",
233
+
"description": "i cried with the new movie.... i cried....",
234
+
"author": "super man lover."
235
+
},
243
236
244
-
"source": "jermakiss.md",
245
-
"url": "jermakiss.html"
246
-
},
247
-
...
237
+
{
238
+
"status": "deleted",
239
+
"id": "EMBARRASINGPOST985",
240
+
241
+
"source": "jermakiss.md",
242
+
"url": "jermakiss.html"
243
+
},
244
+
...
248
245
```
249
246
250
247
The command runs from your project's root directory (where your `makko.json` file is), making that the Current Working Directory. Here's an example in Lua, with the `on_change` property set to `lua ./on_change.lua`:
···
310
307
```json
311
308
// As per makko.json
312
309
"website": {
313
-
"title": "My Makko Blog",
314
-
"description": "Awesome dude type stuff",
315
-
"url": "https://superaweso.me/blog/",
316
-
317
-
"feeds": {
318
-
"html": "index.html",
319
-
"rss": null,
320
-
"atom": "feed.atom"
321
-
}
310
+
"title": "My Makko Blog",
311
+
"description": "Awesome dude type stuff",
312
+
"url": "https://superaweso.me/blog/",
313
+
314
+
"feeds": {
315
+
"html": "index.html",
316
+
"rss": null,
317
+
"atom": "feed.atom"
318
+
}
322
319
},
323
-
320
+
324
321
// As per makko.json and <stdin>
325
322
"custom": {},
326
-
323
+
327
324
// Only valid in "post.html"
328
325
"post": {
329
-
"id": 123456789,
330
-
"is_secret": false,
331
-
332
-
"title": "My awesome post",
333
-
"description": "Dude It's SO awesome. ZOMG",
334
-
"author": "InvaderZimRocks",
335
-
336
-
"tags": ["awesome", "super-cool", "dope-post"],
337
-
338
-
"source": "AWESOME.md",
339
-
"url": "/AWESOME.html",
340
-
341
-
"created": {
342
-
"raw": 123456789, // Milliseconds after unix epoch
343
-
344
-
"year": 2005,
345
-
"month": "06"
346
-
"day": "04",
347
-
348
-
"hour": "19",
349
-
"minute": "46",
350
-
"second": "34"
351
-
},
352
-
353
-
// Same format as "created"
354
-
"updated": { ,., },
355
-
356
-
// Null on anything but "post.html"
357
-
"body": "<h1>ZOMG XD</h1> ..."
326
+
"id": 123456789,
327
+
"is_secret": false,
328
+
329
+
"title": "My awesome post",
330
+
"description": "Dude It's SO awesome. ZOMG",
331
+
"author": "InvaderZimRocks",
332
+
333
+
"tags": ["awesome", "super-cool", "dope-post"],
334
+
335
+
"source": "AWESOME.md",
336
+
"url": "/AWESOME.html",
337
+
338
+
"created": {
339
+
"raw": 123456789, // Milliseconds after unix epoch
340
+
341
+
"year": 2005,
342
+
"month": "06"
343
+
"day": "04",
344
+
345
+
"hour": "19",
346
+
"minute": "46",
347
+
"second": "34"
348
+
},
349
+
350
+
// Same format as "created"
351
+
"updated": { ,., },
352
+
353
+
// Null on anything but "post.html"
354
+
"body": "<h1>ZOMG XD</h1> ..."
358
355
}
359
-
356
+
360
357
// List of all posts, same format as "post" field.
361
358
// Only valid in "feed.html".
362
359
"posts": [...],
363
-
360
+
364
361
// Lists of tags, containing all posts with said tag
365
362
// "posts" is a list of posts with the same format as the "post" field.
366
363
// Only valid in "feed.html".
367
364
"tags": [
368
-
{
369
-
"name": "awesome",
370
-
"posts": [...]
371
-
},
372
-
{
373
-
"name": "super-cool",
374
-
"posts": [...]
375
-
},
376
-
{
377
-
"name": "dope-post",
378
-
"posts": [...]
379
-
},
365
+
{ "name": "awesome", "posts": [...] },
366
+
{ "name": "super-cool", "posts": [...] },
367
+
{ "name": "dope-post", "posts": [...] },
380
368
]
381
-
369
+
382
370
// Lists of posts with X tag, same format as "post" field.
383
371
// Only valid in "feed.html".
384
372
"by_tag": {
385
-
"awesome": [...],
386
-
"super-cool": [...],
387
-
"dope-post": [...],
388
-
...
373
+
"awesome": [...],
374
+
"super-cool": [...],
375
+
"dope-post": [...],
376
+
...
389
377
}
390
378
```
391
379
···
438
426
439
427
440
428
<h1 id="makko-migration">Migrating from makko 1.x to makko 2+</h1>
441
-
442
429
The easiest way to migrate is to let `makko` re-generate a new `makko.json` instead of doing changes manually.
443
430
444
431
To do so, move/rename your `makko.json` to something like `makko.json.bak` and run `makko .` in your directory again.
···
449
436
450
437
451
438
## Migrating Makko 1.x templates
452
-
453
439
For Makko to continue working, you must adjust your templates slightly.
454
440
455
441
in your `templates/post.html`, you must surround any usage of the `body`, `description`, `author` and other post-attributes with a `{{#post}}` and `{{/post}}` like so: