README.md 7.1 KB
Newer Older
1
# Devuan Web Source
2

3
This is the source code for [beta.devuan.org][beta].
4 5
Notice that any merge requests should be based against the `beta.devuan.org`
branch (default branch) and push to `master` is not possible.
6

7 8 9
**Version note**: although this file mentions v0.9.0, it's not tagged
yet.  It will be tagged 0.9.0 when released (on the master branch), and
should reach 1.0 by Jessie.
10

11
__Version 0.9.0__.  We're using [Semantic Versioning](https://semver.org/).
12

13
## License
14

Evilham's avatar
Evilham committed
15 16
The source code is free software distributed under the GNU Affero General
Public License, version 3, or, at your option, any later version. (See
17
[COPYING](./COPYING).)
18

19
The website contents are creative commons released under
20
CC-BY-ND-4.0-International.
21

22
## Contents
23

24
This is a static Web made with [Middleman](https://middlemanapp.com/).
25

26 27
| Directory           | File                   | Description               |
|---------------------+------------------------+---------------------------|
hellekin's avatar
hellekin committed
28 29
| ./                  | config.rb              | Middleman configuration   |
| bin/                | sync                   | Poor man's mirroring      |
30 31 32 33
| etc/                |                        | Extra configuration files |
|                     | nginx-development.conf | To run the site locally   |
|                     | nginx-production.conf  | To deploy publicly        |
| locales/            | :lang.yml              | Localized strings         |
34
| source/             |                        | Web content               |
35 36 37 38 39
| source/layouts      | *.erb                  | Layout templates          |
| source/pages        | *.:lang.html.md.erb    | Localized pages           |
| source/partials     |                        | Partial files (includes)  |
| source/ui           |                        | User interface files      |
| source/ui/css       |                        | Stylesheets               |
Evilham's avatar
Evilham committed
40
| source/ui/css/fonts |                        | Embedded Web fonts        |
41 42
| source/ui/img       |                        | Image files               |
| source/ui/js        |                        | Javascript files          |
43

Evilham's avatar
Evilham committed
44
Most pages go under `source/pages/os/`.  This is to enable local mirrors to
45
add their own custom contents for their local community.
46

47
## Development
48

49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
**Note**: the easiest way to setup a build environment is by using the
provided `Dockerfile`. Even if you don't want to use docker, you may want to
use both `Dockerfile` and `docker_init.sh` as reference to setup your build
environment.

### Using docker

* Build the image with `docker build -t devuan-www .`
* Adapt following to your needs:

    mkdir /tmp/devuan-www
    docker run -it \
      --mount type=bind,source=/tmp/devuan-www,target=/devuan-www/out \
      --mount type=bind,source=$(pwd),target=/devuan-www/src \
      devuan-www

* Now `/tmp/devuan-www` will contain a `build.log` file with useful
  information and a `public` directory with the built site.
* See below for information on how to serve the webpage.
68 69 70

### 0. Pre-requisites

71 72 73
You need Ruby (`sudo apt install ruby-dev`).
The development files are useful to compile some `gems`.
Then you need a couple of ruby packages (`gems`):
74 75 76 77 78

```
~$ sudo gem install middleman bundler
```

79 80 81 82
They will take care of their dependencies.
Lucas Nussbaum and the Debian Ruby team made a fantastic job integrating
Ruby in Debian--hence in Devuan.

83 84 85
### 1. Clone the source code

```
hellekin's avatar
hellekin committed
86
~$ mkdir -p ~/src/devuan/www && cd $_
87 88 89
www$ git clone https://git.devuan.org/devuan-editors/devuan-www.git devuan.org
www$ cd devuan.org
devuan.org$ export DIR=$PWD
90 91
```

92
The source code now lives at `~/src/devuan/www/devuan.org`.
hellekin's avatar
hellekin committed
93
We keep track of this path using the variable `DIR`.
94 95 96 97

### 2. Install the server configuration

```
98 99 100
1 devuan.org$ echo '127.0.0.1 devuan.invalid' | sudo tee -a /etc/hosts
2 devuan.org$ cd /etc/nginx/sites-available
3 sites-available$ sudo ln -s $DIR/etc/nginx-development.conf devuan.invalid
hellekin's avatar
hellekin committed
101
4 sites-available$ cd ../sites-enabled
102
5 sites-enabled$ sudo ln -s ../sites-available/devuan.invalid
hellekin's avatar
hellekin committed
103
6 sites-enabled$ sudo /etc/init.d/nginx reload
104 105
```

Evilham's avatar
Evilham committed
106 107
1. Add a fake host to be able to use the domain

hellekin's avatar
hellekin committed
108
2. to the end: enable nginx configuration
109

hellekin's avatar
hellekin committed
110
### 3. Build the site
111 112 113

```
sites-enabled$ cd $DIR
114
devuan.org$ bundle exec middleman build
115
```
116
This generates the static files in `$DIR/public`.
117

hellekin's avatar
hellekin committed
118
### 4. Browse it
119

120
You can fallback to the backend for non-built files if you run the local
121
middleman server (and edit the NginX configuration):
122 123

```
124
devuan.org$ bundle exec middleman server -p 4569
125 126
```

127
Open your browser to `http://devuan.invalid`
128 129 130 131 132 133 134 135

## Production Deployment

The main site (`beta.devuan.org`) is in English by default.

### Mirrors

Mirrors should change the default language to set theirs in `config.rb`.
136 137
Do commit the change, so that it will be kept during updates.
If you want to push the change, use a branch, e.g., `fr.devuan.org`:
138

139 140 141 142 143 144 145
```
devuan.org$ git checkout -b fr.devuan.org
```

Once your mirror is deployed, please send its URL, language, location,
and person responsible to [the mirror issue][mirror], so it can be added
to the list.  E.g., a mirror in France can be accessed via
hellekin's avatar
hellekin committed
146
fr.devuan.org.
147

148 149 150
You're welcome to announce your mirror in the [Mirroring Devuan][t45]
discussion space.

151
[beta]: https://beta.devuan.org/
152 153
[mirror]: https://git.devuan.org/devuan-editors/devuan-www/issues/1
[t45]: https://talk.devuan.org/t/mirroring-devuan/45
hellekin's avatar
hellekin committed
154 155 156 157 158 159

# Content Production

## Creating Pages

- pages go to `source/pages/os`
160 161 162 163
- name the file: `source/pages/os/your-slug-title.en.html.md.erb` where
 `en` stands for English.  Adjust locale to the ISO two-letter code for
 language.  Example:
 `source/pages/os/documentation/howto-create-new-pages.en.html.md.erb`
Evilham's avatar
Evilham committed
164

165 166 167 168 169
 The weird extension chain ensures that `middleman` will go through
 Embedded ruby (erb), Markdown (md), HTML, and the translation engine
 (en).  The final extension will be `.en.html`.  You can edit in
 Markdown, HTML5, and Embedded Ruby (erb).  Normally Markdown will
 suffice.
Evilham's avatar
Evilham committed
170

171 172 173 174 175
 Running `bundle exec middleman build` will generate the static HTML in
 `public/os/documentation/howto-create-new-pages.html`.  Note that the
 primary language does not appear in the path.  If you're building a
 page in another language, say French, it will appear in
 `public/os/documentation/howto-create-new-pages.fr.html`.
Evilham's avatar
Evilham committed
176

177
### Front matter
Evilham's avatar
Evilham committed
178

hellekin's avatar
hellekin committed
179 180 181
 We use the _YAML front matter_ to set variables such as the page title,
 or its sibling pages.  Please refer to existing pages for examples.
 Here is a list of common variables:
Evilham's avatar
Evilham committed
182

183
 | Variable | Value                                      | Where?                |
hellekin's avatar
hellekin committed
184 185 186 187 188 189 190 191 192
 |:---------|:-------------------------------------------|:----------------------|
 | title    | Some Descriptive Title                     | All pages             |
 | topic_id | number matching a topic in talk.devuan.org | pages with discussion |
 | prev     | **HTML link** to previous page             | /os (prev-next)       |
 | up       | **HTML link** to parent resource           | /os (prev-next)       |
 | next     | **HTML link** to next page                 | /os (prev-next)       |

You can also set your own variables or use data files in `data/`.
Please refer to [Middleman documentation](http://middlemanapp.com/doc).
Evilham's avatar
Evilham committed
193

hellekin's avatar
hellekin committed
194 195 196
## Editing Pages

Thank you for contributing!