README.md 2.67 KB
Newer Older
1 2 3
## McCLIM website management ##

McCLIM uses the
Daniel Kochmański's avatar
Daniel Kochmański committed
4 5
[sclp](https://gitlab.common-lisp.net/dkochmanski/sclp) as a base for
it's website. This short tutorial will describe the deployment
Jan Moringen's avatar
Jan Moringen committed
6
process. To build the website we use
Daniel Kochmański's avatar
Daniel Kochmański committed
7 8
[coleslaw](https://github.com/kingcons/coleslaw) – a static website
generator.
9 10 11

### Adding content ###

Jan Moringen's avatar
Jan Moringen committed
12 13 14
To add a news entry you have to clone the repository and add a new
file (using markdown syntax with an extra header) to the directory
`posts/`:
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

```markdown
;;;;;
title: Awesome blog entry
tags: tag1, tag2, my-awesome-tag-3
date: 2016-05-22 12:30
format: md
author: John Doe
;;;;;

The blog entry content follows.
* Point 1
* Point 2
* [Point 3](https://point-3.example.org)

Voila.
31 32
```

33
The steps for creating a static page are almost the same. You need to
Jan Moringen's avatar
Jan Moringen committed
34 35
put the file in the `pages/` directory and provide a slightly
different header which indicates the URL:
36

37 38 39 40
```markdown
;;;;;
url: new.html
;;;;;
41

42
Page content follows.
43 44
```

45 46 47
Additionally, if you want to create this website entry on the
navigation bar, you need to edit the `.coleslawrc` file's section
`:sitenav` (the section is self-explanatory).
48

Jan Moringen's avatar
Jan Moringen committed
49 50
If you want to modify an existing page or news item just edit the file
and commit all changes.
51

52 53
### Adding files not suitable for git ###

Jan Moringen's avatar
Jan Moringen committed
54 55 56 57
GIT isn't well suite for hosting big files. To add new "heavy" files
to the website put them in the `/project/mcclim/files` directory – on
deployment all files in it will be put in the `static/files` website's
relative path.
58

Jan Moringen's avatar
Jan Moringen committed
59
Smaller files which belong to the repository should be added to the
60 61 62 63
`static/` directory (any subdirectory will be fine except `files/`,
which is listed in `.gitignore` and reserved for big files on the host
system.

64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
### Testing changes locally ###

To test changes locally, change the relevant lines of `.coleslawrc` to
something like:

```lisp
:staging-dir "/tmp/mcclim-website/staging"
:deploy-dir "/tmp/mcclim-webstie/public_html"
```

then load the `coleslaw` system and call its `main` function:

```lisp
(ql:quickload :coleslaw)
(coleslaw:main "PATH-TO-MCCLIM-WEBSITE-REPOSITORY" :deploy nil)
```

This will put the generated website in the
`/tmp/mcclim-website/staging` directory (or whichever directory you
configured). Note that links in the generated files still refer to the
online version of the website.

86
### Deployment ###
87

Jan Moringen's avatar
Jan Moringen committed
88
After modifying the website, commit the change and push it to the
Daniel Kochmański's avatar
Daniel Kochmański committed
89
repository. After that login to your common-lisp.net shell account and
90
run the script:
91 92

```shell
93
/project/mcclim/bin/regen.sh
94 95
```

96
After this step the website should be deployed.
97 98 99 100 101

### References ###

* [SCLP repository](https://gitlab.common-lisp.net/dkochmanski/sclp)
* [Coleslaw documentation](https://github.com/kingcons/coleslaw)