README.md 3.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Common-Lisp.net site generator

## Directory structure

The source code for the site generator is located in the
root of the repository. The `t/` directory contains tests
for the site generator.

The site content is divided over the directories `content/`
and `layout`.

The `layout/` directory holds all content
that applies to more than one page (e.g. templates) and
everything that's referenced from such components (e.g.
logo and other images or CSS), or is used to override
such a component (e.g. a template which overrides the
default template). Referred content, such as stylesheets,
scripts and images are located in `layout/static/*`.

20
21
The `content/` directory holds the individual content items (pages)
and everything that's referred from that content, but not referred
22
23
from layout content. E.g.  the `index.html` page — defining the
site's front page — is located in `content/` as well as any images
24
25
26
that are included on the front page but not included on any template
content. Referred content, such as stylesheets, scripts and images are
located in `content/static/*`
27
28
29
30
31
32
33

The `content/` directory can contain both `html` files and `lisp`
files. `html` files are processed with the template stuff directly
into the `output/` directory. `lisp` files are expected to have a call
to `cl-site:add-content` as their toplevel form, which takes arguments
of `:headers-plist` and `html-string`. See `content/about.lisp` for a
reference example.
34
35
36
37
38
39
40
41
42
43

If a file by the same name is stored in both
`layout/static/` and `content/static/`, then the one
in `layout/static/` takes precedence. 

## Dependencies

* CL-MUSTACHE for HTML templating
* CL-YAML for YAML "header" parsing
* CLOSER-MOP (because...?)
44
45
46
47
48
* CL-WHO for LHTML processing
* MARKDOWN.CL for Markdown processing

(these are all called out in the cl-site.asd file and will be fetched
 automatically by Quicklisp)
49
50
51

## Execution

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

### From command line 

Using Make.

The Makefile contains various useful commands. 

Among them:

* `make` - to generate the site.
* `make serve` - to run a simple site server on port 8008 or subsequent (currently needs Allegro CL, SBCL, or CCL)
* `make clean` - to remove the generated files from output directory
* `make pyserve` - to run a secondary (python) server on port 8000 (crashes if 8000 is busy).



### From Lisp 
69

70
(The following assumes you have a reasonably recent Quicklisp loaded)
71

72
* Either (in one fell swoop):
73

74
     (load ".../cl-site/build.lisp") ;; replace with your actual path to cl-site/
75

76
77
78
79
 This will also start serving the site on port 8008 (or subsequent port
 numbers, if 8008 is busy). So you can visit the site to test it at:

  `http://localhost:8008`
80

81

82
* Or (step by step):
83

84
85
86
87
88
 First, make sure your `cl-site/` directory (the directory containing
 this file) is pushed onto `ql:*local-project-directories*` or you
 have this directory moved or linked under your
 `quicklisp/local-projects/` directory (see `build.lisp` for example
 of how to push onto `ql:*local-project-directories*`).
89

90
 Then, load the system with this command:
91

92
     (ql:quickload :cl-site)
93

94
 To generate the site: 
95

96
     (cl-site:make-site)
97

98
 The output files will be generated in the `output/` directory.
99

100
 To clean any old files from output/ directory:
101

102
     (cl-site:make-clean)
103
104


105