http://geoserver.org

This repository contains the source for the GitHub generated GeoServer home page.

Reporting issues

If you stumble into any issue with the GeoServer web site please report it in our Jira issue tracker using the website component.

Developing

The site is built with Jekyll:

#. Before you start:

gem install bundler jekyll jekyll-feed jekyll-paginate jekyll-sitemap

If anything is missed:

bundle install

On macOS with apple silicon:

bundle update ffi

#. Jekyll can be run in "watch" mode for development:

bundle exec jekyll serve --watch

The site contents will be served at http://localhost:4000.

See TEST.md for more details.

#. Commit to main branch and the result is published to http://geoserver.org

Blog

Blog posts are managed as part of the website.

To create a new blog post:

1. Create a new markdown page in _posts following the filename convention for sort order:

   _posts/2021-05-04-may-the-fork-be-with-you.md

2. The post is published using the metadata included at the top of your file.

   ---
   author: Andrea Aime
   date: 2021-05-04
   layout: post
   title: May the fork be with you!
   categories:
   - Developer notes
   ---
   

3. Popular categories include:

   • Developer notes
   • Announcements -- used for project team and release announcements
   • Tips and Tricks
   • Tutorials
   • User perspectives

Releases

When a release is performed, the site contents are updated to reflect the new release. Below is the process of updating site contents for a stable release.

1. Write a blog post announcing the new release:

   cd bin
   python3 announcement.py username password 2.23.2 --geotools  29.2 --geowebcache 1.23.2
   

   username and password are your JIRA credentials.

   A post is generated to stdout for your review.

   If everything looks good generate a post using (the date for the generated post is supplied by Jira):

   python3 announcement.py username password 2.23.2 --geotools  29.2 --geowebcache 1.23.2 --post
   

   See script instructions for more information, python3 anouncement --help for more options.

   note: At the start of a new series (when making a milestone or release candidate) a new bin/templates/about22?.md template will be required for the script to work.

2. Release posts have the following format

   ---
   author: Andrea Aime
   layout: post
   title: GeoServer 2.19.3 Released
   categories:
   - Announcements
   tags:
   - Release
   release: release_219
   version: 2.19.3
   jira_version: 16816
   ---
   

   The following information is used to generate a release/<version>/index.html page:

   • release: This is the _layout used for the generated release page

   • Tags are used to indicate Release, Release Candidate, Milestone.

     The Vulnerability tag is used to highlight blog posts and release announcements covering a security topic.

   • version: The GeoServer version being announced

   • jira_version: Used to link to the release notes

     The value for jira_version can be found by navigating to that version on Jira and examining the URL. For example, for example, 2.7.2 links to https://osgeo-org.atlassian.net/projects/GEOS/versions/10601, giving a jira_version of 10601. For a maintenance or development release, instead modify release/maintain/index.html or release/dev/index.html respectively.

3. Check one of the previous blog posts so we end up with a consistent format.

   • GeoTools and GeoWebCache version numbers will need to be supplied on the command line
   • Check the "about section" at end of post with links to documentation / proposals / presentations

4. Update _config.yml (this change will be reflected in index.html and download/index.html):

   • Update stable_jira to be the same as the next release, this is used for the Nightly build page.

     stable_jira:      16821
     

   • For a maintenance instead change maintain_jira.

     maintain_jira:    16819
     

Dev Releases

When publishing the first milestone, beta or release candidate for a series:

1. Create a new _layouts/release_<version>.html template by copying the previous template and adding an entry for any new extensions that have been released on the new branch.

   This is the value used for release when making your announcement blog posts.

   Create bin/templates/about_XXX.md highlighting new features.

2. Update _config.yml update dev_series and dev_branch, the matching release announcement post will be used to generate release/dev/index.html page.

   dev_series:       2.21.x
   dev_branch:       2.21.x
   

3. Update the main_series, and main_jira to reflect the new version number for main branch, this will be used to generate a placeholder for release/main/index.html page.

   main_series:       2.22.x
   main_jira:        16829
   

Final Release

When creating the final release:

1. Update the _config.yml properties:

   • Update the maintain_branch using the values from stable.
   • Update the stable_branch.

2. Update the main_series and main_series information. For example, when starting the series 2.22.x:

   main_series:      2.22.x
   main_jira:        16829_
   

3. The dev_series and dev_branch property in _config.yml to the new series, these will no longer match any posts as the development period is over:

   dev_series:       main
   dev_branch:       2.22.x
   

Technical Details

Jekyll Build

The Jekyll build process goes through several steps:

1. The file _config.yml is parsed into Jekyll::Site

   • site.data

2. Makes an inventory of existing content:

   • site.pages contains instances of Jekyll::Page for each page (and post) defined.

   • site.static_files contains Jekyll::StaticFile

3. Our custom plugin _plugins/release.rb generator is run:

   • Processes the posts in site.pages, add additional Jekyll::PageWithoutAFile entries to site.pages
   • Creates a site.data.releases data structure listing all the releases found for use by the download/index.html page.

4. Additional plugins are run:

   • jekyll-feed: generates an Atom feed of all the posts
   • jekyll-sitemap: generates a sitemap of all the pages
   • jekyll-paginate: uses _blog/index.html as a template to generate page2.html, page3.html, ... page80.html

5. At this point all the site.pages are created each containing:

   • page.title
   • page.content
   • page.url
   • page.date
   • page.id
   • page.dir
   • page.name
   • page.data provided by front-matter at the top of the file

   Release pages have:

   • page.data.version
   • page.data.jira_version
   • page.data.release_date
   • page.data.announce

6. Jekyll process any pages with Liquid into static files in the _site folder.

   • Variable reference use {{ and }}:

     Download the latest [GeoServer {{site.stable_version}}](/release/stable/index.html) release.
     

   • Variable filters use | pipe character to define a processing chain:

     Released {{ page.date | date_to_long_string }}.
     

   • Tags used to define control flow:

     {% for release in site.data.releases | where: "series", "2.19"  %}
       {{ release.version }}
     {% endfor %}
     

   Here is a decent cheatsheet for reference.

Publishing

Commit to main and the result is published.

Technical details:

1. Commit to the main branch.

2. Workflow .github/workflows/build-jekyll.yml action is triggered.

   • Uses ubuntu-latest environment

   • Uses JEKYLL DEPLOY ACTION

     • Runs Jekyll build to generate static files (just like normal)

     • Commits the resulting static files to the gh-pages branch

3. GitHub pages settings is configured to publish the gh-pages branch to https://geoserver.github.io.

   • The CNAME geoserver.org is used but we have yet to obtain the domain from Planet Federal.

   The content is available as the https:/geoserver.org website