ref: 4e4d4ae7d3573f3b14e9453aba4f74afe785d32e betterssg/README.md -rw-r--r-- 3.7 KiB View raw
                                                                                
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
## Description

betterssg is good for generating simple websites like
[tom.preston-werner.com](http://tom.preston-werner.com/) and
[osa1.net](https://osa1.net/). Use betterssg if you want to avoid [The
Bullshit Web](https://pxlnv.com/blog/bullshit-web/).

UPDATE June 2019: I'm not planning to continue developing this
project, although I'm still using it for my personal website:
[wrycode.com](https://wrycode.com). As of now, all documented features
work well, but I have not done extensive testing.

## Installation

To build from source, install the dependencies via
[Quicklisp](https://www.quicklisp.org/beta/), and run `./build`.

~~Support for Windows and macOS is planned, but I have not tested on
either platform.~~ The source code is already cross-platform (in
theory), so if you want to test it you can `(asdf:load-system
:betterssg)` and then use `(betterssg:main)` to build your site instead
of running the executable.

## Usage

`$ ./betterssg`

There are currently no command-line arguments; all configuration is
done in the file `config.lisp`. 

To view a preview of the website, I recommend using Python's built-in
HTTP server. From the shell:

`$ python -m http.server 8080 --directory website/`

## File Organization

Inspect the files in the folders `content/default/` and
`layout/default/`. The content folder stores the markdown files
that betterssg will process into finished HTML pages. The layout
folder stores the HTML (and CSS, and, if you must, Javascript)
that makes up each finished webpage.

I recommend copying `content/default/` and `layout/default/` into two
new folders named after your website (like `content/my-website/` and
`layout/my-website/`). Make sure to change the variables
`:content-folder` and `:layout-folder` in the `config.lisp` file.

*Content*

The name of each markdown file in the content folder represents the
title of the webpage. "example-title.md" will become "EXAMPLE
TITLE". To group pages under a generated blog-style page, simply copy
them to a directory named after the page (e.g. "blog/"). To date a
page, prefix the filename with ten digits representing the date
(e.g. "2019-03-13-my-first-post.md"). 

Ergo, all metadata is stored using the filesystem.

The top-level file `home.md` will become the homepage of the website.

`media/` is a separate folder that will get copied into `website/`
when betterssg is run. It can include files of any type, including HTML.

*Layout*

Currently, the layout folder is very simple. The file `page.html`
is the template for each generated webpage. It is a normal HTML file 
with four optional variables:

 - head: the contents of the `head.html` file (which
   can sometimes get quite large)
 - title: the title of the page, or nothing if there is no title
 - date: the date of the page, or nothing if there is no date
 - content: the content from each markdown file (converted to
   html, of course)
   
## About

betterssg is opinionated. Simplicity is a priority. Want tags, complex
user-defined taxonomies, a domain-specific language, thousands of
themes, and a program that calls itself an *engine*? Use
[Hugo](https://gohugo.io/). Want to just make your website, already?
Use betterssg.

## Planned Features

- ~~HTML or plain text files in the content folder~~
- ~~Javascript-free syntax highlighting of code blocks~~
- RSS feed generation
- XML sitemap generation
- `--server` argument for running and refreshing a local webserver
- options regarding title case and date format

## Idiosyncrasies

- dated pages with no title must still have the trailing dash in the
  date: `2019-03-13-.md`
- for preformatted code, you must indent the region four spaces in the
  markdown file. Triple backticks and  `<pre>` are not working correctly

## Other TODOs

- ~~release for Windows and macOS~~