How is www.debian.org made

The Debian “webtree”, collection of directories and files that comprise our web site, is located in the /org/www.debian.org/www directory on www-master.debian.org. The bulk of the pages are normal static HTML files (i.e. not produced with something dynamic such as a CGI or a PHP script), because the web site is mirrored.

The site is generated in one of three ways:

An automatic update (from the CVS repositories and other sources to the webtree) is being run six times a day.

If you'd like to contribute to the site, do not simply add to or edit items in the www/ directory. Contact the webmasters first.

All the files and directories are owned by group debwww and writable by that group, so the web team can modify files in the web directory. The 2775 mode on directories means that any files created under that directory will inherit the group - debwww in this case. Anyone in group debwww is expected to set 'umask 002' so that the files are created with group write permissions.


Look & feel

We give the pages the same look and feel by having WML do all the detail work of adding headers and footers to pages. Although a .wml page may look like HTML at first glance, HTML is only one of the types of extra information that can be used in .wml. After WML is finished running its various filters over a file, the final product is true HTML. To give you an idea of the power of WML, you can include Perl code into a page to allow you to do, well, almost anything.

Note however that WML checks (and sometimes automagically corrects) only the very basic validity of your HTML code. You should install weblint and/or tidy to validate your HTML code.

Our web pages currently comply to the HTML 4.01 Strict standard. We intend to move on to XHTML, however, so all web editors are strongly encouraged to write the HTML tags in lowercase, place ending tags where appropriate, etc., in order to make the transition as smooth as possible.

Anyone who is working on a lot of pages should install WML so they can test to make sure the result is what they want. If you are running Debian, you can easily install the wml package. Read the pages on using WML for more information.

Sources

The source for the web pages is stored under CVS. CVS is a version control system, which allows us to keep a log of which, who, when, and why changes occurred, etc. It is a safe way to control the concurrent editing of source files among multiple authors, which is crucial for us because the Debian web team is rather large in size.

If you are unfamiliar with this program, you will want to read the pages on using CVS.

The topmost webwml directory in the CVS repository contains directories named after the languages the web site is in, two makefiles and several scripts. The translation directory names should be in English and lowercase (e.g. "german", not "Deutsch").

The more important of the two makefiles is Makefile.common, which, as its name says, contains some common rules which are applied by including this file in the other makefiles.

Each of the language directories contains makefiles, WML source files and subdirectories. The file and directory names do not differ in order to keep the links correct for all languages. The directories may also contain .wmlrc files which contain some information useful to WML.

The webwml/english/template directory contains special WML files that we call templates, because they can be referenced from all other files using the #use command.

In order for changes in the templates to propagate to the files which use them, the files have makefile dependencies on them. Since a vast majority of the files use the "template" template, by having a "#use wml::debian::template" line at the top, the generic dependency (the one for all files) is that very template. There are exceptions to this rule, of course.

Scripts

The scripts are mostly written in shell or Perl. Some of them are standalone, and some of them are integrated into WML source files.

The sources for the main www-master rebuild scripts are in the debwww/cron Git repository.

The sources for the packages.debian.org rebuild scripts are in the webwml/packages Git repository.

How to help

We invite everyone interested to help us make the Debian site as good as it can be. If you have valuable information related to Debian that you think our pages are missing, share it with us and we'll see that it gets included.

We could always use help with designing pages (regarding graphics and layouts), and keeping our HTML clean, too. We regularly run the following checks on the whole web site:

Help is always welcome in reading the above logs and fixing the problems.

The current build logs for the web site can be found at http://www-master.debian.org/build-logs/.

If you're a fluent English speaker, we'd like you to proof-read our pages and report all errors to us.

If you speak another language, you may want to help us translate the pages to your language. If a translation has already been made, but has problems, take a look at the list of translation coordinators and talk to the leader for your language about fixing it. If you'd like to translate pages yourself, see the page on that topic for more information.

There's also a TODO file, check it out.

How not to help

[Q] I want to put fancy web feature into www.debian.org, may I?

[A] No. We want www.debian.org to be as accessible as possible, so

[Q] I have this nice idea. Can you enable FOO in www.debian.org's HTTPD, please?

[A] No. We want to make life easy for administrators to mirror www.debian.org, so no special HTTPD features please. No, not even SSI. An exception has been made for content negotiation. This is because it is the only robust way to serve multiple languages.