]> Git in Space - ssg/blob - README
Add $FILE feature and remove test files
[ssg] / README
1 ### Static Site Generator ###
2
3 SSG is a collection of scripts for simplified generation of basic static
4 websites.
5
6 # CONTENT FILES
7
8 A Content File is a file used to represent page content for the site. Such a
9 file is stored simply as plain text and is copied across exactly as that. This
10 plain text may include arbitrary HTML wherever desired.
11
12 The key feature being that any line started with `;;` will - rather than being
13 copied verbatim to output - instead be executed as a shell command. This grants
14 access to limitless flexibility for the automatic generation of site content.
15
16 Content Files *must* have a `.cf` file extension as this is how SSG determines
17 which files to process.
18
19 # AFFIX FILES
20
21 An Affix File is named either `PREFIX` or `SUFFIX`. When processing a file, if
22 one or both of these files are found in the same directory as the file being
23 processed then the `PREFIX` file will be prepended and the `SUFFIX` file will be
24 appended to the main content. This allows easy templating of basic page
25 structure without having to explicitly request headers and footers in every
26 file.
27
28 # BUNDLED SCRIPTS
29
30 SSG comes included with a collection of stock scripts and functions to make
31 creating sites simpler and reduce the amount of boilerplate code required. Some
32 examples of these bundled scripts include:
33
34 include FILE
35 Includes the contents of FILE for processing.
36 index
37 Generates a file index for the current directory, automatically omitting
38 various files such as affix files and hidden files/directories and handling
39 file extensions where possible.
40 git-history
41 Presents commit history for the current file in a simple format.
42
43 By default, these scripts are expected to be in `$XDG_DATA_HOME/ssg` falling
44 back to `~/.local/share/ssg`. All files in this directory are sourced when
45 invoking ssg.
46
47 Functions called from within content and affix files have access to the `$FILE`
48 variable that contains the path to the initial file passed to SSG.
49
50 # USAGE
51
52 ssg FILE
53 Reads FILE and processes it, writing the output to stdout.
54
55 The simplest way to use SSG is to create a site root e.g. `./www` and in that
56 directory place all the files for your site, using `.cf` files instead of
57 `.html` files where desired, then a Makefile like this can be used:
58
59 CFFILES = $(wildcard www/**.cf)
60
61 site: $(FILES)
62
63 %.html : %.cf
64 ssg $< > $@
65
66 clean:
67 rm -f www/**.html
68
69 NOTE: this assumes you have no `.html` files that aren't generated from `.cf`
70 files. If you do, then running `make clean` will delete them.