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
|
# DS-Static
DS-Static, the Dead Simple Static Website Generator.
## Who DS-Static is For
I had the idea for DS-Static when trying to find a static generator for my website and ran into some problems.
- I previously used Makesite, but I wasn't in the mood to read and change it's source again.
- I searched other static generators, but disliked their technical complexity, i.e using Node.JS
- Others nad much user complexity, such as Hugo. I wanted a generator that would be more efficient to learn and use, than it would be to hand-write my HTML, assuming I regularly use it.
Feeling there was nothing that fit the bill, I decided to write my own. I have written two other static site generators in the past but they were too obtuse for others to pick up. I wanted other people to make use of this too.
I devised a set of goals.
- Technically uncomplicated, keep LOC low.
- Conceptually simple, quick to start using.
- No requirement to read or modify source code.
Of these I kept the first two, the third is technically broken but the code modification of the user is minimal, i.e setting some variables and maybe changing the shebang line.
If you are creating a personal or business website, a blog, a gallery, or some other sort of content-focused website, are familiar with HTML/CSS, and have similar requirements to me, you may find DS-Static useful for yourself.
## Installation
1. If you do not have it already, install **Tcl**. The program was written for Tcl 8.6 and above, but will likely run fine on slightly older versions.
2. Check the shebang line of `main.tcl` points to your Tcl interpreter. On Linux systems this is usually `/bin/tclsh` (the default) but across systems it can differ. Run `whereis tclsh && whereis tcl8.6` to find where yours is located.
3. If you do not have it already, install **pandoc**.
## Usage of Program
### Instructions for Use
1. Read and modify `config`.
a. `d_source` is the source of content.
b. `d_output` is where generated files are put.
c. `replacement` is a dictionary for simple, global replacements.
2. Write templates in `templates/` directory. Templates are written using Tags; read the next section regarding their use.
3. Populate your `d_source` directory with content.
### Warnings and Notes
- User errors are likely to present as Tcl errors.
- A loop in the template layout will cause a 'waiting' program.
- Files in the output directory will be overwritten.
## Tags
DS-Static's fundamental concept is the tag, which are HTML comments that take on special meaning in this program. There are three types.
**Templates** are HTML snippets contained in `templates/`.
**Variables** are 'global' key-value pairs, specified before runtime in the `config` file.
**Document Variables** are 'local' key-value pairs, specified within a document.
### Templates
Template tags are of the form `<!--TEMPLATE-->`, i.e uppercase HTML comments by convention.
Templates can be organized into folders for your convenience, and are then addressed as `<!--DIR1/DIR2/TEMPLATE-->`
There are three templates used within the program you must not delete (though you can and should modify) in `templates/core/`.
- `index` is used for generating an index for many files.
- `entry` is used for an entry in the aforementioned index.
- `page` is the default template for a markdown page.
A reserved template tag is `<!--CORE/CONTENT-->` which is not an actual file, but is internally used as the placeholder for where post contents may go internally.
A warning for templates; the program does not check for recursive templates. It is the user's responsibility to write templates in a hierarchical manner.
### Variables
Variable tags are of the form `<!--variable-->`, i.e lowercase HTML comments by convention.
In the file `config.tcl` the user will find a variable named *replacement*, which is a Tcl dictionary. There is documentation explaining how the dictionary works, but I hope it should be straightforward to see.
### Document Variables
Document Variables are of the form `<!-- key: value -->`. The case and whitespace is to the users preference.
In either a Markdown or a HTML document, the user can include these for certain parameters they wish to configure, such as title, subtitle, author, or other document metadata.
Two pieces of metadata are automatically generated; *date* which is the last modified date, and *filename* which is the relative address.
## Errors
Some errors the user may come across and what they mean.
child process exited abnormally
while executing
"exec ls -t | grep -v ~$ | grep -v index.html"
Likely you have no other files to process besides index.html
|
