Skip to main content
This page discusses technical aspects behind the JMRI website at jmri.org and also providing parts of the help system in JMRI.
If you just want to know how to make a small change to a web or help page, please see the Updating JMRI Documentation instructions.
We distinguish between three types of information on the main website:
We provide these separately:
JMRI/websiteGitHub repository and placed directly on the website.
Page formatting is done using CSS, originally set up by John Plocher. All pages should reference the CSS files for screen and printing from the "/css" directory. This also means that you should leave the formatting to the style sheets, and minimize the explicit formatting that you do in HTML directly.
We are using server-side includes to provide consistent headers, sidebars and footers. This allows us to share HTML content between the web and the JmriHelp system used by the program itself. Each page will contain just content, plus includes for files named "Header", "Sidebar" and "Footer" which contain the navigation information. Eventually, all but a few index pages will have ".shtml" extensions. (The remaining index.html pages keep that name so that people who request just a directory URL will be served something useful).
We are using .htaccess files to do redirects when a web page is removed. This lets older bookmarks continue to work. The hardware/.htaccess file provides an example. For more information on the syntax, see the Apache mod_rewrite documentation.
The website contains several separate areas:
JMRI/JMRIrepository They are only occasionally referenced directly.
Another group are from the
JMRI/website repository, and are checked
out at the root of the web server.
Finally, some of the site is generated from the JMRI source itself, as opposed to being contained in the source. The Javadoc is one such section, along with some of the human-readable information about defined decoders.
Most of the website contents is updated hourly from jobs running on one of the project's Jenkins build servers. The directories listed above constitute most of the site, and this content is updated from the JMRI repository without any additional work.
The regeneration of the Javadoc and xml content involves significantly more work than merely updating a directory, and so these are only done once per day, as needed, by the Generate Website job on the production Jenkins server.
If you want to host a copy of the JMRI website on your local Mac OS X machine, follow these instructions to first configure the Apache server to do server-side includes, and then make a copy of the website files available to the server.
A similar process may work for Linux (or even Windows) systems with Apache installed.
# This may also be "None", "All", or any combination of "Indexes", # "Includes", "FollowSymLinks", "ExecCGI", or "MultiViews". # # Note that "MultiViews" must be named *explicitly* --- "Options All" # doesn't give it to you. # Options Indexes FollowSymLinks MultiViews
Options Includes Indexes FollowSymLinks MultiViews
# # To use server-parsed HTML files # #AddType text/html .shtml #AddHandler server-parsed .shtmland un-comment the last two lines so that it looks like
# # To use server-parsed HTML files # AddType text/html .shtml AddHandler server-parsed .shtmlThen find the reference to the include_module and make sure it's loaded by a line like:
LoadModule include_module libexec/apache2/mod_include.soBy default, that's commented out with a leading # character.
DocumentRoot "/Library/WebServer/Documents" Directory "/Library/WebServer/Documents"There's an indented section directly below that. Find the part that looks like:
# # AllowOverride controls what directives may be placed in .htaccess files. # It can be "All", "None", or any combination of the keywords: # AllowOverride FileInfo AuthConfig Limit # AllowOverride NoneChange the last line to allow overrides (which is what a .htaccess file does):
AllowOverride AllThen find the reference to the rewrite_module and make sure it's loaded by a line like:
LoadModule rewrite_module libexec/apache2/mod_rewrite.soBy default, that's commented out with a leading # character.
JMRI's website uses index.shtml files as index pages. To make sure that those will display by default, e.g. if you use a partial URL like https://jmri.org/download, find the line containing "DirectoryIndex" and add "index.shtml" to the existing list of index-like file names.
We also want PHP turned on, so that the indices for the resources pages will work. Find the follow line and make sure it's not commented out:
LoadModule php5_module libexec/apache2/libphp5.so
~me/git/website/setSymLinks.sh ~me/git/JMRI ~me/git/websitewhere "~me/git/website" is the path to the JMRI/website repository that you just checked out, and "~me/git/JMRI" is the path to the JMRI/website repository.
setSymLinks.shsets up symbolic links that let your web server see the top of the JMRI website as if the files were directly present.
Many JMRI XML files contain XIncludes that reference other XML files with URLs like "http://jmri.org/xml/schema/types/turnouts-2-9-6.xsd". When a JMRI program encounters those, it automatically converts those to a local file reference. Other tools, like NetBeans and xmllint, don't know how to do that.
Installing a local XML catalog, and then telling your tools to use it, can solve this.
<?xml version='1.0'?> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <rewriteURI uriStartString="http://jmri.org/xml/" rewritePrefix="http://localhost/xml/" /> </catalog>