How www.debian.org is made
The Debian website is a collection of directories
and files located in
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.
.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
For more information, have a look at the using WML page.
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.
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
- The file
Makefile.commonis 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
.wmlsource 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
.wmlrcconfiguration file with additional commands and preferences for WML.
- The directory
webwml/english/templatecontains special WML files which work as templates. They can be referenced from all other files with the
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
the generic dependency, so they contain the following line at the top:
There are exceptions to this rule, of course.
The scripts are mostly written in shell or Perl. Some of them work standalone, and some of them are integrated into WML source files.
This Git repositors contains all the scripts used to update the Debian web site,
i.e. the sources for the
This Git repository contains the sources for the
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 (
ddpGit 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:
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.
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.
[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.