README.md 3.78 KB
Newer Older
ale's avatar
ale committed
1 2 3 4 5 6 7
Autistici.org website
=====================

This repository contains the source code for the autistici.org
website.

Contents are written in Markdown, and rendered to static HTML at
ale's avatar
ale committed
8
deployment time.
ale's avatar
ale committed
9

ale's avatar
ale committed
10
# Making changes
ale's avatar
ale committed
11

ale's avatar
ale committed
12 13 14
The website contents are located in the `src` subdirectory. Pages are
encoded in Markdown, with a small header providing page metadata
(mostly the page title).
ale's avatar
ale committed
15

ale's avatar
ale committed
16 17 18 19 20 21 22
The header is YAML-encoded, and it must be separated from the page
content with a line containing only four dashes (`----`).  For
example:

    title: About
    ----
    Contents of the about page.
ale's avatar
ale committed
23

ale's avatar
ale committed
24 25 26 27 28 29 30
When editing the website sources, it is a good idea to test the
results locally, before submitting the changes. In order to do so,
there are some setup steps you will need to perform on your system.

## Requirements

To build the website, a few tools will need to be installed:
ale's avatar
ale committed
31 32
[gostatic](https://github.com/piranha/gostatic) to generate the HTML
pages, and [sitesearch](https://git.autistici.org/ai/sitesearch) to
ale's avatar
ale committed
33 34 35 36
generate the search index. The scripts will automatically download and
install these tools if necessary, but you will need a working
[Go](https://golang.org/) development environment.  Furthermore,
testing the website requires running a local Apache server.
ale's avatar
ale committed
37

ale's avatar
ale committed
38
On a Debian system, you can install all the requirements with:
ale's avatar
ale committed
39

ale's avatar
ale committed
40
    $ sudo apt-get install rsync golang-go
ale's avatar
ale committed
41 42 43 44 45 46 47 48 49 50 51 52

## Testing changes for correctness

There are a few static checks that you can run after modifying the
website. They will check for broken internal links, bad syntax, and
other things. You can invoke the lint script that runs these checks
with:

    $ ./scripts/lint.sh

If this scripts does not output anything, the tests have passed
successfully.
ale's avatar
ale committed
53

ale's avatar
ale committed
54 55 56
It is a good idea to set up the linter script as a git *pre-commit*
hook, to make it impossible to commit a change that does not pass
these tests successfully:
ale's avatar
ale committed
57

ale's avatar
ale committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
    $ cat >.git/hooks/pre-commit <<EOF
    #!/bin/sh
    exec ./scripts/lint.sh
    EOF
    $ chmod +x .git/hooks/pre-commit

## How to build the website

Simply run, from the top-level directory:

    $ ./scripts/update.sh

The resulting HTML pages will be found in the `public` directory.

## How to run a test webserver

To check the results of your edits, it is useful to start a local
ale's avatar
ale committed
75 76 77 78 79 80 81 82 83 84 85
webserver to inspect the generated HTML pages. In general, you
might want to avoid installing the Apache packages on your local
system (especially on Debian where they automatically start
daemons), so we have prepared a way to install Apache in a
chroot. Run the following commands just once to set it up:

    $ sudo apt-get install debootstrap
    $ sudo ./scripts/install-apache.sh

Then, to start Apache and the search daemon, run (it may ask
you for your password due to the use of *sudo*):
ale's avatar
ale committed
86

obaz's avatar
obaz committed
87
    $ sudo ./scripts/run-test-server.sh
ale's avatar
ale committed
88 89 90 91 92 93

This will start a full server stack (web server and search server)
that you can access by browsing to

    http://localhost:3300

ale's avatar
ale committed
94 95 96 97
To stop the Apache process when you're done, run:

    $ ./scripts/run-test-server.sh stop

ale's avatar
ale committed
98

ale's avatar
ale committed
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
## Updating the FAQ

FAQ pages are currently stored in an old format (compatible with
the *makefaq* tool). Just update them regularly and `update.sh`
will handle them correctly.

## Embedding external data sources

It is possible to use dynamically-generated data in the templates by
placing a script in the `data.d/` directory. The script must be
executable, and its name should not contain dots. Its output must
be valid JSON.

Data from these scripts will be collected in a single dictionary
in the file `data.json`: the data returned by each script will be
present with a key named as the script.

Files ending in `.md_in` will be preprocessed by the template engine
(using the Go html/template syntax) before being rendered into HTML.

As an example of this technique, you can check out:

* `data.d/dns`
* `src/docs/web/domains.en.md_in`