How www.debian.org is made

• Look & Feel
• Sources
• Scripts
• Generating the Website
• How to help
• How not to help... (FAQ)

Look & Feel

The Debian website is a collection of directories and files located in /org/www.debian.org/www on www-master.debian.org. Most pages are static HTML files. They don't contain dynamic elements like CGI or PHP scripts, because the website is mirrored.

The Debian website uses the Website Meta Language (WML) to generate the HTML pages, including headers and footers, headings, table of contents, etc. Although a .wml file might look like HTML at first glance, HTML is only one of the types of extra information that can be used in WML. You can also include Perl code into a page and therefore do almost anything.

After WML is finished running its various filters over a file, the final product is true HTML. Please note that although WML checks (and sometimes automagically corrects) the basic validity of your HTML code, you should install a tool like weblint and/or tidy as syntax and minimal style checker.

Anyone who is regularly contributing to the Debian website should install WML to test the code and make sure the resulting HTML pages look right. If you are running Debian, simply install the wml package. For more information, have a look at the using WML page.

Sources

We use Git to store the Debian website's sources. The version control system allows us to keep track of all changes and we can see who committed what and when, even why. Git offers a safe way to control the concurrent editing of source files by multiple authors — a crucial task for the Debian web team, because it has a lot of members.

Read more about Git

Here is some background information on how the sources are structured:

• The topmost directory in the Git repository (webwml) contains directories named after the respective pages' language, two Makefile and several scripts. Directory names for translated pages should be in English and use lowercase letters, for example german and not Deutsch.
• The file Makefile.common is especially important, as it contains some common rules which are applied by including this file in the other Makefiles.
• All the subdirectories for the different languages also contain Makefiles, various .wml source files, and additional subdirectories. All file and directory names follow a certain pattern, so that every link works for all the translated pages. Some directories also contain a .wmlrc configuration file with additional commands and preferences for WML.
• The directory webwml/english/template contains special WML files which work as templates. They can be referenced from all other files with the #use command.

Please note: to ensure that changes in the templates get propagated to the files which include them, the files have Makefile dependencies on them. A vast majority of the files use the template template, the generic dependency, so they contain the following line at the top:

#use wml::debian::template

There are exceptions to this rule, of course.

Scripts

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

• webmaster-team/cron: This Git repositors contains all the scripts used to update the Debian web site, i.e. the sources for the www-master rebuild scripts.
• webmaster-team/packages: This Git repository contains the sources for the packages.debian.org rebuild scripts.

Generating the Website

WML, templates, and shell or Perl scripts are all the ingredients you need to generate the Debian website:

• The majority is generated using WML (from the Git repository).
• The documentation is generated with either DocBook XML (ddp Git repository) or with cron scripts from the corresponding Debian packages.
• Some parts of the website are generated with scripts using other sources, for example, the mailing list (un)subscription pages.

An automatic update (from the Git repository and other sources to the webtree) is being run six times a day. Apart from that, we regularly run the following checks on the whole website:

• URL check
• wdg-html-validator
• tidy

The current build logs for the website can be found at https://www-master.debian.org/build-logs/.

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

How to help

We encourage anyone to help with the Debian website. If you have valuable information related to Debian which you think is missing, please get in touch — we'll see that it gets included. Also, please have a look at the above mentioned build logs and see if you have suggestions for fixing a problem.

We're also looking for people who can help with the design (graphics, layouts, etc.). If you're a fluent English speaker, please consider proof-reading our pages and report errors. If you speak another language, you may want to help to translate existing pages or help with fixing bugs in already translated pages. In both cases, please have a look at the list of translation coordinators and get in touch with the responsible person. For more information, please have a look at our page for translators.

Read our TODO list

How not to help... (FAQ)

[Q] I want to include this fancy feature in the Debian website, 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 I want to submit. Can you enable foo or bar in www.debian.org's HTTP server, 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 (Server Side Includes). An exception has been made for content negotiation, because that's the only robust way to serve multiple languages.

Back to the Debian Project homepage.