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:
- the bulk of it is generated using WML, from the
- the documentation is generated either using DocBook XML (use of DebianDoc
SGML is being phased out), from the
ddpSubversion repository; or using cron scripts, from the corresponding Debian packages
- parts of the site are generated using scripts using other sources, e.g. the mailing list (un)subscription pages
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.
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.
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.
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
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.
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.
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.
[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
- no browser specific "extensions".
- no relying on images only. Images may be used to clarify, but the information on www.debian.org must remain accessible via a text-only web browser, like lynx.
[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.