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
|
# Crocc
Crocc is a simple static-site generator based on Markdown.
The main goal of Crocc is to offer simplicity, as opposed to other static-site
generation tools such as Hugo or Jekyll.
Indeed, you only need Markdown to write content in a productive manner, and
everything else is standard scripts (JavaScript, CSS, images, etc.).
## Usage
Let's say you have a directory containing the following files:
```
src/
├── .crocc.html
├── index.md
├── about.md
├── bar.png
└── contact.md
```
The `.crocc.html` file is the template used to generate the HTML pages.
The `index.md`, `about.md` and `contact.md` files are Markdown documents.
The `bar.png` file is a static file.
To generate the HTML files, run the following command:
```bash
$ crocc -out=dst -url="http://example.com" -sitemap src
```
The `dst` directory will contain the following files:
```
dst/
├── index.html
├── about.html
├── bar.png
├── contact.html
└── sitemap.xml
```
You can now upload the `dst` directory to your web server and you're done!
## Documentation
### Input/output directory
The input directory is the directory containing the various files used to
build the site.
The input directory must contain a `.crocc.html` file, which is the
template used to generate the HTML pages.
> Only the top-level template is used. Nested templates are not supported.
The output directory is the directory where the generated HTML files will be
written.
The output directory must not exist before running Crocc.
Crocc will copy all the files in the input directory to the output directory,
except the `.crocc.html` file.
During the copy, Crocc will transform Markdown documents to HTML files.
### Markdown document
The Markdown document must have a YAML header, also known as "front matter".
The YAML header is a set of key-value pairs separated by a colon.
The YAML header is followed by the Markdown document.
Front matter keys:
* `title`: The title of the document. Required.
* `description`: The description of the document. Required.
* `publication_time`: The date of the document. Required.
* `last_update_time`: The date of the last update of the document. Not required.
* `keywords`: The tags of the document, as a list of strings. Required.
* `author`: The author of the document. Default is `""`.
* `hide`: If set to `true`, the document will not be generated.
Default is `false`.
Example:
```md
---
title: Hello World
description: This is a simple example of a Markdown document.
publication_time: 2020-01-01T00:00:00Z
last_update_time: 2020-01-01T03:00:00Z
keywords: [example, hello, world]
author: John Doe
hide: true
---
# Hello World!
```
### Page template
To create HTML pages, Crocc uses a template file.
The template file, written in HTML using Go template syntax, must be located in
the `$INPUT/.crocc.html` file.
The template file is injected with a set of variables. A variable can be used
in the template file using the `{{ .VariableName }}` syntax.
Read the [Go template documentation](https: //golang.org/pkg/text/template) for
more information.
The following variables are available:
* `.Title`: The title of the document.
* `.Description`: The description of the document.
* `.PublicationTime`: The date of the document.
* `.LastUpdateTime`: The date of the last update of the document.
* `.Keywords`: The tags of the document, as a string separated by commas.
* `.Author`: The author of the document.
* `.Content`: The content of the document, as HTML.
* `.Site`: The URL of the site.
* `.Generator`: A string containing the name and version of the generator.
* `.Sitemap`: The URL of the sitemap.
Here is a sample template:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ .Title }}</title>
<meta name="description" content="{{ .Description }}">
<meta name="keywords" content="{{ .Keywords }}">
<meta name="author" content="{{ .Author }}">
<meta name="generator" content="{{ .Generator }}">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<header>
<h1>{{ .Title }}</h1>
</header>
<main>
{{ .Content }}
</main>
<footer>
<p>
Last update: {{ .LastUpdateTime }}
</p>
</footer>
</body>
</html>
```
## License
The project is governed by a BSD-style license that can be found in the
[LICENSE](LICENSE) file.
|
