The easiest way to install released versions of the Markup Validator is to use the packages created for some platforms by contributors: Mac OS X, openSUSE/SUSE Linux, Debian GNU/Linux and Fedora/Red Hat packages are available.
The installation guide we provide here is a rather generic set of instructions, which should work on most systems. To our knowledge, the following platform-specific guides are also available and can be of interest :
This installation guides presumes knowledge of the Source availability for the Markup Validator.
We recommend that developers wishing to contribute on the Markup Validator or modify it go through this installation procedure once, to get familiar with the system.
These instructions are strongly inspired from Nick Talbott's guide for Slackware Linux. Thanks Nick!
The installation guide assumes that you have a working Web server. We suggest the popular Apache server, which is used for the W3C Markup Validation service. The validator may work with other Web servers than the popular Apache, but we cannot guarantee that it will. You will also need a working installation of the Perl language (standard on most Web servers).
Apart from a properly configured Web server, the Validator needs a SGML parser -- that does all the hard work --, Perl (version 5.8.0 or newer) and several Perl modules used by the "check" CGI script.
The following few steps will guide you through installing those prerequisites, and then the validator itself
The SGML parser we're currently using is
which can be found on the
OpenJade home page.
Note that the validator will not work with any version of OpenSP earlier than 1.5.2.
If you install opensp from source, make sure to enable HTTP retrieval of DTDs. Disabling the building of documentation
Run the following as root/administrator, or under sudo
[unpack opensp] ./configure --enable-http --disable-doc-build make make install
Run the following as root/administrator, or under sudo
perl -MCPAN -e shell [cpan shell starts, you may need to answer configuration questions] install Bundle::W3C::Validator
You may skip this if you have successfully installed the bundle above.
Below are the Perl modules required to run the Markup Validator. This list is informative, you do not need to install them individually if you follow the CPAN instructions above.
Accept-EncodingHTTP header with version 5.816 and later, depending on if the modules required for libwww-perl's compression facilities are installed. If you want your Validator to support SSL/TLS, see README.SSL included in the libwww-perl distribution.
The Perl modules listed below are optional; the validator will use them to provide some extra functionality if they're available.
Alternatively, if you want to work on the latest development version, you can download both from our Mercurial repository, but you should be aware that this version may not work at all.
(Read more about retrieving the source)
Create a directory for the validator's installation. On Unix-based systems,
we suggest to use the default folder
directory will be referred to as
throughout this guide.
Unpack the two archives of the validator and sgml-lib into a
temporary directory, and copy the directories
# tar zxvf validator.tar.gz # tar zxvf sgml-lib.tar.gz # mkdir /usr/local/validator # cd validator-X.Y # mv htdocs share httpd/cgi-bin /usr/local/validator
[validatorpath] directory should now have
Create the directory
/etc/w3c and copy all the files
[validatorpath]/htdocs/config/ to it. You may keep
the configuration files in place, but would have to modify the Web
Server's environment variables to point to the configuration directory.
As this may be tedious, we recommend using
/etc/w3c/validator.conf to reflect where files
are in your installation, and configure other parameters there as
you wish. This file is well commented and modifying it should be
In general you will only need to check
that the Base path is set to where you have unpacked the validator
files. If you have used
/usr/local/validator you do not need
to change anything
Base = /usr/local/validator
If you plan to validate documents on a private network, you will need to enable
the following option in the
Allow Private IPs = yes
If you want to check documents with the (external and experimental) HTML5 conformance checker, you may want to install the validator.nu engine and enable it with the following in your validator.conf file:
<External> ## Enable checking documents via external services HTML5 = http://localhost:8888/html5/ </External>
You may now test the validator script, before plugging it into the Web Server:
# cd /usr/local/validator/ # cd cgi-bin/ # ./check uri=http://www.w3.org/ …
The script should output the raw HTML results of validation. If this does not work, double-check that you have properly followed all the steps so far.
You may skip this, unless you plan to modify the validator's default behavior..
The following instructions are for the Apache Web server, and should be adapted if you plan on using another server.
If you are using the Apache server, you may use the validator under mod_perl2. This should happen automatically if you are using the httpd.conf snippet distributed with the validator or something similar, and your Apache server has mod_perl2 installed and enabled. Using mod_perl2 will bring important performance benefits, but has not been tested extensively. If you are successfully running the validator under mod_perl, or run into issues doing so, contact us.
Also worth enabling within Apache is mod_expires, which will allow caching of the validator's static documents, stylesheets, and images.
Edit the configuration of your Web server to refer to the specific configuration file for the validator.
This can be done by inserting the contents of the
httpd/conf/httpd.conf file (from where you
unpacked the validator's tarball above) in your
httpd.conf, or by copying the file somewhere
and including it like:
Then, start editing the validator specific part.
You may want to set up a "virtual server" for the service. This can be done by adding something similar to the following :
<VirtualHost 127.0.0.1> DocumentRoot [validatorpath]/htdocs/ ServerName validator.example.org </VirtualHost>
AND/OR you may want to have the service at a specific location on your Web server, which can be configured as follows :
Alias /validator/ [validatorpath]/htdocs/
Finish editing this HTTP server configuration file, adapting all the directory references to reflect the paths used in your installation.
Now restart the Web server to activate the updated configuration.
this is done by typing into a shell, as System Administrator:
apachectl graceful (or, for older versions of Apache
apachectl configtest then
Point your browser at the new site.
Check the error log of the Web server to get clues on what may be wrong if you get any server errors.
Help us improve this installation guide by sending us your feedback if you install the validator on your local system!
It is not always easy to troubleshoot an incomplete, or failed, installation of the Markup Validator. While the instructions given in this page should help most people install the validator successfully on their system, bad luck, a forgotten step or a broken component can make things go sour.
The first sound thing to do if the installation failed would be to check that you did not forget any step while installing. properly copying and editing the configuration file is among the common mistakes, for example.
The error logs for your Web server should be a good first place to look for hints on what is wrong with your installation.
A common problem with a newly installed validator is a validator that is apparently running but marking anything as "invalid", without giving any error message as output.
This is somewhat typical of a problem with OpenSP. Cross-check that you actually have a version above 1.5, by running onsgmls --version.
If the validator is misbehaving, you can try forcing various debug options by appending to the URL the following string: &debug=1
This can sometimes provide you with error messages that would not have appeared anywhere in non-debug mode, and can be helpful to diagnose the problem
Don't hesitate to contact the public mailing-list firstname.lastname@example.org with all the details you can provide on what you did, tried, and what went wrong...
if the installation succeeded, you should be able to now use the Markup Validator on your own
system and network. You may want to give the validator a look and feel specific to your Web site.
The easiest way to achieve this is to edit
htdocs directory), the header and footer markup snippets used to build all
pages for the validator.
You may also edit the Style Sheets (in the same directory),
base.css You may however want to avoid editing the other CSS files too
heavily, there is a risk you could make the output of the validator unusable.
If you edit any *.css or *.js files, make sure that you update the gzipped versions of the edited files as well if they're installed and content negotiation for them is enabled in your setup (both are usually true if the validator was installed following these instructions).
The Validator Team wishes to thank Nick Talbott and Stephen Yoch for their help in creating these installation instructions. Thanks also to all the people who use and review the guide to make it better and better!