Site management

This page explains how the Apache SIS web site is created and how to update the site. The intended audiences are SIS release managers and SIS web site maintainers.

General documentation about Apache Content Management System (CMS) can be found in the CMS reference page. The remaining of this page is specific to the SIS project.

Directory layout

The source files for the Apache SIS web site can be fetched from Subversion using the following command:

svn checkout https://svn.apache.org/repos/asf/sis/site/trunk site

The directory layout is as below, omitting version numbers in file names. The * character stands for an arbitrary amount of files having the given extension.

site
├─ css
│  ├─ bootstrap.min.css
│  └─ sis.css
├─ img
│  └─ *.png
├─ js
│  ├─ bootstrap.js
│  └─ jquery.js
├─ content
│  └─ *.mdtext
└─ templates
   ├─ single_narrative.html
   └─ skeleton.html

All files with the .mdtext extension use the Markdown format, which is described there:

New .mdtext files can be created using the site-management.mdtext file as a template. Those files can be modified in any text editor and committed with the usual Subversion commands. Each commit will trig a new site build, which will be visible in the staging area at http://sis.staging.apache.org. The build progress can be monitored on the Buildbot page, but they are usually very fast. Once a staging site has been approved, it can be published to http://sis.apache.org as below:

Content

All .mdtext files should start as below (replace the <...> block by the corresponding content):

Title:  <put the page title here>
Notice: <copy the notice from an existing page>

The title will appear both in the browser window title bar, and as a header at the beginning of the generated HTML page. The notice should be followed by a short abstract of the page content (typically a single paragraph), then a Table Of Content to be automatically generated:

[TOC]

The first header appears after the table of content. For each header, and anchor should be specified using the {#...} syntax. Do not rely on automatically generated anchors, since they may not be stable if some text in the header is modified. Example:

My first header in my page    {#firstHeader}
============================================

Style sheets

The following table lists the style sheets used by Apache SIS. The Maven and Javadoc style sheets are mentioned for completeness, but are not located on the web site repository. They are rather located together with the SIS library source code.

Page set File Purpose Remark
Web site content/css/bootstrap.min.css Main appearance Generated from the Twitter's Bootstrap project.
Web site http://www.apache.org/css/code.css Code highlighting Located on the foundation-wide Apache server.
Web site content/css/sis.css SIS-specific style Overwrite bootstrap.min.css, edited manually.
Maven site src/site/resources/css/site.css Maven site Overwrite maven-base.css, edited manually.
Javadoc src/main/javadoc/stylesheet.css Javadoc appearance Copy of javadoc output, edited manually.

Updating bootstrap

If the bootstrap.min.css file needs to be updated, then visit the Bootstrap web site and select the following options:

  • Scaffolding
    • Body type and links
    • Grid system
    • Layouts
  • Components
    • Navs, tabs, and pills
    • Navbar
  • Miscellaneous
    • Wells
  • Base CSS
    • Code and pre
  • JS Components
    • Dropdowns

If additional options are needed, then select the minimal amount of new options. Do not select an option that may be used; select only the options that are actually going to be used. Then:

  • Update this page for listing the new options.
  • Download the bootstrap.zip file and unzip in the content directory, overwriting the existing files.
  • Delete css/bootstrap.css, since it is not used.
  • Add the following comment in css/bootstrap.min.css, just below the copyright header:

bootstrap.min.css:

/*
 * This file is automatically generated - DO NOT EDIT.
 * See http://sis.apache.org/site-management.html
 */