Devuan Web Source

This is the source code for beta.devuan.org.

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.

Version 0.9.0. We're using Semantic Versioning.

License

The source code is free software distributed under the GNU Affero General Public License, version 3, or, at your option, any later version. (See COPYING.)

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

Contents

This is a static Web made with Middleman.

| Directory | File | Description | |---------------------+------------------------+---------------------------| | ./ | config.rb | Middleman configuration | | bin/ | sync | Poor man's mirroring | | etc/ | | Extra configuration files | | | nginx-development.conf | To run the site locally | | | nginx-production.conf | To deploy publicly | | locales/ | :lang.yml | Localized strings | | source/ | | Web content | | 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 | | source/ui/css/fonts | | Embedded Web fonts | | source/ui/img | | Image files | | source/ui/js | | Javascript files |

Most pages go under source/pages/os/. This is to enable local mirrors to add their own custom contents for their local community.

Development

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.

0. Pre-requisites

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):

~$ sudo gem install middleman bundler

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.

1. Clone the source code

~$ mkdir -p ~/src/devuan/www && cd $_
www$ git clone https://git.devuan.org/devuan-editors/devuan-www.git devuan.org
www$ cd devuan.org
devuan.org$ export DIR=$PWD

The source code now lives at ~/src/devuan/www/devuan.org. We keep track of this path using the variable DIR.

2. Install the server configuration

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
4 sites-available$ cd ../sites-enabled
5 sites-enabled$ sudo ln -s ../sites-available/devuan.invalid
6 sites-enabled$ sudo /etc/init.d/nginx reload

1. Add a fake host to be able to use the domain

2. to the end: enable nginx configuration

3. Build the site

sites-enabled$ cd $DIR
devuan.org$ bundle exec middleman build

This generates the static files in $DIR/public.

4. Browse it

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

devuan.org$ bundle exec middleman server -p 4569

Open your browser to http://devuan.invalid

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. 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:

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, so it can be added to the list. E.g., a mirror in France can be accessed via fr.devuan.org.

You're welcome to announce your mirror in the Mirroring Devuan discussion space.

Content Production

Creating Pages

• pages go to source/pages/os
• 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

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.

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.

Front matter

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:

Variable	Value	Where?
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.

Editing Pages

Thank you for contributing!