README.md 4.48 KB
Newer Older
Aral Balkan's avatar
Aral Balkan committed
1 2 3 4
# Small Technology Foundation web site

This is the web site for the Small Technology Foundation.

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
It is a static site generated using Hugo (currently v0.55.6) and served using [Site.js](https://sitejs.org).

## Installation

  - Install [Hugo](https://gohugo.io/getting-started/installing)
  - Install [Site.js](https://sitejs.org)

## Development

```sh
./develop
```

This will start up Hugo and Site.js and run the site locally at https://localhost.

__Note:__ Development, staging, and deployment scripts require Site.js v12+.

## Staging

```sh
./stage
```

This will start up Hugo, Site.js, and ngrok at your hostname, which you should have mapped to ngrok.

## Deployment

```sh
./deploy
```

If you have SSH access to the server, this will deploy your latest changes to https://small-tech.org.

38 39 40 41 42 43 44 45
## Adding content

### Pages and posts

Standard pages and posts are added in the usual Hugo way, using `hugo new posts/title/index.md`.

### Partials

46
Repeated partials, such as the `layout/partials/fund-us.html` or `layout/partials/footer.html` copy are included in some templates. The fund-us partial can also be included within markdown files using the `{{ < fund-us > }}` shortcode.
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
## Fund Us and Patronage Pages

### Overview of implementation and where to find relevant files

The Fund Us page is a static page generated by Hugo.

The Patronage pages are _dynamic_ pages.

Both are served by Site.js.

### Fund Us page

 - __Content:__ `/content/fund-us/`
 - __Layout:__ `/layouts/fund-us/list.html`

The Fund Us page contains the funding form and uses the fully client-side Stripe Checkout flow. The payment form is hosted by Stripe and we simply redirect the donor to it once they’ve selected their donation type (donation or patronage) and amount. When they successfully complete a transation, they are either returned to `/fund-us/thank-you/` (for donations) or to their own patronage page, as specified by the inclusion of the Stripe session ID within the URL.

### Patronage page(s)

 - __Content:__ /themes/small-tech/static/.dynamic/`
 - __Layout:__ uses the page template generated by Hugo at `/content/template.md`

Within the `.dynamic` folder:

 - `client/`: has client side HTML, CSS, and JS. The CSS and JS, along with patronage-specific variables are injected into the patron.html file which is then itself injected into the layout template specified above.
 - `https/get/patron.js`: the HTTPS GET route that gets called by Stripe after a successful patronage subscription. This route renders the patronage page.
 - `wss/patrong.js`: the websocket route. The patronage page communicates with this route via a WebSocket connection to allow for the updating, pausing, and cancellation of patronages using the Stripe API.

### Testing
77 78 79

Currently, it’s a bit more difficult to develop/test the Fund Us flow and Patronage pages as the former requires remote access to the machine you are testing on and the latter requires the Site.js server to serve the public directory (the `develop` and `stage` scripts, on the other hand, run Site.js to proxy Hugo’s server, which gets us live reload functionality for static content).

80
#### Fund Us donation flow
81 82 83

You can test the Fund Us Stripe flow using the `stage` script __for one-time donations only__. You cannot test the Stripe flow using the `develop` script, which runs a server at `localhost` instead of at your hostname.

84
#### Fund Us patronage flow and the Patronage pages
85 86 87 88 89 90 91 92 93 94 95

Run the `funding` script instead of `stage`.

Note that you will lose LiveReload.

To see changes:

  - For changes to static assets (page copy, CSS, etc.): reload the page in the browser
  - For dynamic changes (if you change server-side JavaScript in the `.dynamic` folder): restart the `funding` script and reload the page.

## A note on graphics and compression
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121

### Image resolutions

For full-width images, the largest resolution we support is 4K (3,840 width) @ 1.5x. So a full-width header is 5,760 pixels wide.

For smaller graphics, render them at 2x.

### Header compression settings

We compress the header PNGs using [compress-or-die.com/png](https://compress-or-die.com/png) in 4 colour. The full set of settings are below. All are defaults apart from the Colors settings, set in bold:

#### Preprocessing

  - Size: 100%
  - Trim: no
  - Blurring radius (px): 0
  - Blurring threshold (px): 0

#### Compression

  - Bit depth: 8 Bit
  - __Colors: 4__
  - Dithering: yes
  - Extreme compression: no


Aral Balkan's avatar
Aral Balkan committed
122 123 124
## Copyright and license

Copyright ⓒ 2019 Small Technology Foundation
125
[Licensed under AGPLv3 or later](LICENSE).