qgis/qgis-website

QGIS-Website

This repository is meant to manage the Official website of QGIS, a free and Open Source Geographic Information System (GIS) Software, under the Open Source Geospatial (OSGeo) foundation umbrella.

• Development (Quick Start)
• Building the website using Docker
• Building the website using Make
  • Build on macOS or Linux
  • Build on Windows
• Translating
• Styling the website
• Publishing safely using rsync
  • Server configuration

QGIS Website is a static generated website using Sphinx, based on restructured text sources (rst) and html (jinja2) templates.

Most sources are in source/site. Only front page and landing pages are in themes/qgis-theme. Styling is in themes/qgis-theme.

Note: The notes provided here are for manual setup, push and publish of the web site. As of QGIS Hackfest 24 in Florence, Italy, August 2022, we also have GitHub workflow automation. Please see the ./github/workflows folder for insight into the process used. Also see the Publishing safely using rsync section further down in this document for notes on how to set up the server to receive the docs.

Development (Quick Start)

# move into the dir of this repo:
cd QGIS-Website
# perform the actualy building of the html (using our 'qgis/sphinx_html_3' image)
docker run -t -i -v `pwd`:/QGIS-Website -w=/QGIS-Website --rm=true qgis/sphinx_html_3 make html
# now serve the output of the build on port 80 (usign nginx image) so you can view it in your browser
docker run -p 80:80 -v `pwd`/output/html:/usr/share/nginx/html nginx
# open it in your browser:
open http://localhost/en/site/
#  (make sure there is not another webserver running on port 80, if so change to another port in the nginx start above, eg 8000 and then use http://localhost:8000/en/site)

Building the website using Docker

TLDR: cd QGIS-Website && ./docker-run.sh html

Note: you will use a QGIS docker image from hub.docker.com, created with the dockerfile from:

https://github.com/qgis/QGIS-Sysadmin/blob/master/docker/sphinx/Dockerfile-html

First: install Docker.

On Linux: use your package manager.

On Windows: install boot2docker from: https://boot2docker.io/ Some notes: you need admin rights to do this: the install script will generate some keys, just accept all defaults. If it does not work the first time, check if you need to 'enable virtualization' in your BIOS (eg Lenovo disables it by default).

Start a command box (on Windows: double click the boot2docker icon on desktop, you will get a terminal):

Verify that Docker/Boot2docker is working by typing:

docker run hello-world

If all goes ok, it will download a small Docker image and you will have an output like this:

richard@kwik~$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from hello-world
....
Hello from Docker.
This message shows that your installation appears to be working correctly.

Now we are going to create a working directory and pull the sources from github, either your own fork or the original QGIS repo like here:

# cd to your home dir
cd
# create a dev dir and move into it
mkdir dev
cd dev
# clone/copy the sources into it and go into the dir
git clone [email protected]:qgis/QGIS-Website.git
cd QGIS-Website
# check your current path
pwd
# ^^^ that shows your current path, with me on Linux it is:
/home/richard/dev/QGIS-Website
# on Win7 and Win8 I had:
/c/Users/richard/dev/QGIS-Website

We are now going to use that QGIS-Website directory as the source and output directory for the Docker 'virtual machine' that will build the site. We will start this Docker container with a command line like below:

docker run -t -i -v /home/richard/dev/QGIS-Website:/QGIS-Website -w=/QGIS-Website --rm=true qgis/sphinx_html_3 make html

Where "docker run -t -i qgis/sphinx_html_3 make html" means: "run a Docker container/process based on the qgis/sphinx_html_3 image available online, call make in the working directory of the container, with parameter 'html', meaning: only build english html"

"-v /home/richard/dev/QGIS-Website:/QGIS-Website" means: use the directory "/home/richard/dev/QGIS-Website" as a virtual directory in the container and name it '/QGIS-Website'

"-w=/QGIS-Website" means that it is to be used as the working dir of Docker

"--rm=true" means remove the container after the build

Now the actual command lines:

On linux (use your own repo path here!):

# english html
docker run -t -i -v /home/richard/dev/QGIS-Website:/QGIS-Website -w=/QGIS-Website --rm=true qgis/sphinx_html_3 make html

On windows (tested on Win7 and Win8), use your own repo path here!

IMPORTANT you need 2x a double // in the command !!! Without it you will get an error message about a wrong working directory:

docker run -t -i -v //c/Users/richard/dev/QGIS-Website:/QGIS-Website -w=//QGIS-Website --rm=true qgis/sphinx_html_3 make html

Note: only the first time it will pull the qgis/sphinx_html_3 image (>300Mb) from the online repository https://hub.docker.com/u/qgis/

Now if you want to build a translated website, there is some more work to do. We have to pull the translations from transifex etc. You need your own transifex credentials to do this. So first get an account/password at www.transifex.com and then create a so-called '.transifexrc' file which is used to authorize you at transifex. The contents of this file should be like this:

[https://www.transifex.com]
rest_hostname = https://rest.api.transifex.com
token = yourtransifextoken

Copy this file to the root of your repo. With me, that is /home/richard/dev/QGIS-Website. NOW you can run it using 'make full' and a LANG parameter like this:

# french html (linux)
docker run -t -i -v /home/richard/dev/QGIS-Website:/QGIS-Website -w=/QGIS-Website --rm=true qgis/sphinx_html_3 make full LANG=fr

Besides this, you can also have a look into the scripts docker-run.sh and docker-world.sh which are used on our own webservers.

Building the website using Make

1. If not provided by your OS, you need to install:

   • git
   • and Python3

   You can install both in default places and with default options.

2. Clone the repository

3. Go into that directory and follow the next instructions depending on your OS.

The best way to build the website is within a Python Virtual Environment (venv).

Build on macOS or Linux

1. You can create your own virtual env:

   # you NEED python >3.6. Depending on distro either use `python3` or `python`
   # common name is 'venv' but call it whatever you like
   
   python3 -m venv venv  # using the venv module, create a venv named 'venv'
   

2. Then activate the venv:

   source ./venv/bin/activate
   

   With 'activated' virtual environment, you should see 'venv' in the prompt.
3. Install the requirements via the REQUIREMENTS.txt:

   pip install -r REQUIREMENTS.txt
   

4. And run the build from within that venv:

   make html
   

   Want to build your own language? Note that you will use the translations from the .po files in the i18n folder within the repository! For example for 'nl' do:

   make LANG=nl html
   

Build on Windows

1. Create a virtual environment called 'venv' in that directory (search the Internet for Python Virtual Env on Windows for more details), but in short: use the module 'venv' to create a virtual environment called 'venv'

   # in dos box:
   python -m venv venv
   

2. Then activate the venv:

   venv\Scripts\activate.bat
   

   With 'activated' virtualenv, you should see 'venv' in the prompt.
3. Install the requirements via the REQUIREMENTS.txt:

   pip install -r REQUIREMENTS.txt
   

4. And run the build from within that venv, using the make.bat script with the html argument to locally build the docs:

   make.bat html
   

   Want to build your own language? Note that you will use the translations from the .po files in the i18n folder within the repository! For example for 'nl' do:

   set SPHINXOPTS=-D language=nl
   make.bat html
   

Translating

We rely on the Transifex platform to store and coordinate our translation efforts. To be part of the translation team, please follow becoming a translator.

New English strings in the repository are automatically pushed and made available on Transifex platform thanks to the tx_push Github action. This action also calls the create_transifex_resources script ensuring that the Transifex configuration file is always up to date.

Translated strings are pulled from Transifex to our servers as part of the daily build process (see Makefile full rule).

Sometimes, the process may fail or you may want to build the site locally with new strings in translated language. In this case, you need to manually pull the translations from Transifex to your local repository:

1. Checkout locally the repository and target branch in git

2. Prepare the environment

   python3 -m venv venv
   source ./venv/bin/activate
   pip install -r REQUIREMENTS.txt
   

3. Install Transifex command line client

   curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
   

4. To gather new strings in a pot (.po) file for your language, and merge them with existing translations in the po files (normally to be run by your language maintainer):

   make pretranslate LANG=xx  # where xx is your language code
   

5. To add a new language (the scripts will need some directory structure):

   make createlang LANG=xx
   

6. Download the translated strings with commands in the Makefile. By default this pulls all the languages.

   # --minimum-perc=1 so only files which have at least 1% translation are pulled
   # -f to force, --skip to not stop with errors
   tx pull --minimum-perc=1 --skip -f
   

   To pull a specific language (e.g. italian), do

   tx pull --minimum-perc=1 --skip -f -l it
   

   IMPORTANT: to be able to pull from transifex.com, you will need a credentials file. This file should be named: .transifexrc and easiest is to put it in your home dir. The file should contain this:

   [https://www.transifex.com]
   rest_hostname = https://rest.api.transifex.com
   token = yourtransifextoken
   

7. Build the docs in your language

   make html LANG=yourlanguage
   

8. Share the changes by opening a pull-request, allowing us to integrate the new strings for the pulled language(s)

Styling the website

Most javascript and css is in theme/qgis-style/ files.

theme/qgis-style/qgis-style.css is based on Less (see http://lesscss.org/ )

To make changes to CSS on MacOSX

download / install / open Less app (http://incident57.com/less/)
in Finder navigate to themes/qgis-theme/static/
drag qgis-style.less file to the Less app
make changes in qgis-style.less
on save it should automatically compile into qgis-style.css
for advance usage read docs on Less CSS: http://lesscss.org/

(if you have any questions ping yulka_plekhanova on Skype)

To make changes on cli Linux

# install node-less and the compressor
sudo apt-get install node-less yui-compressor
# compile the less file to a normal css file:
lessc qgis-style.less qgis-style.css
# or
lessc qgis-style.less > qgis-style.css
# optional: compress the css
yui-compressor -o qgis-style.css qgis-style.css

Publishing safely using rsync

In this section we describe how you can set up a small cloud server to receive the static content produced by sphinx, suitable for publishing on the internet.

Server configuration

We use a CX11 Hetzner cloud machine configured with an external volume as per the image below:

Using the external volume allows us to grow the disk without needing to upgrade the server itself.

The configuration of this server is simple: We set up a non-privaledged user that is only allowed to rsync files to a specific directory. In the steps below we show the process for doing this.

useradd runner -m -d /home/runner
su - runner
mkdir .ssh
chmod 0600 .ssh
cd .ssh/
rm id_rsa*
echo 'command="/usr/bin/rrsync -wo /mnt/HC_Volume_22264126" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDAca8gta0y4esFE8Ro9nq9uOPWvd9+M7kK9DZ84tIxI runner@qgis' > authorized_keys
chmod 0600 authorized_keys
exit
chown runner /mnt/HC_Volume_22264126

Then the Github action worker is set up to upload files to /mnt/HC_Volume_22264126 - see the ./github/workflows for details.

Next we need to harden the server a little and set up NGINX to publish the files that are pushed to the HC_Volume_22264126 folder.

echo "PasswordAuthentication no" >> /etc/ssh/sshd_config
systemctl restart sshd
# installed by default on newer ubuntu distro versions
apt install unattended-upgrades
apt install fail2ban
# Install crowdsec host protection
curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.deb.sh | sudo bash
apt-get install crowdsec
apt install nginx
vim /etc/nginx/sites-enabled/default.conf

Now change the site root to use the volume directory.

root /mnt/HC_Volume_22264126;

Then restart nginx and push a little temp folder to test with:

systemctl restart nginx
su - runner -c "echo 'hi' > /mnt/HC_Volume_22264126/index.html"

Now in cloudflare create a DNS entry. For testing we create a new subdomain, but ultimately you should create it in the root domain:

You will see our site is not yet secure:

So we set up certbos:

Next get a Letsencrypt certificate for the site: `

apt install snapd
snap install core; snap refresh core
snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx

Then open the site in your browser to test:

qgis-website's Issues

Page menus should be switchable

on a per page basis (short pages>no menu, long page>shoulder menu)

Fix images in Commercial Support Page

http://new.qgis.org/html/en/site/forusers/commercial_support.html

external links

We think that it is wise to open external links (eg from the TOC of just in text anyway?) top open them in an external window.
This makes that users do not loose there context where they were (the qgis website).

Currently I'm not able to let Sphinx add some 'target="_blank" attribute in the external links. While at least in the tocs it 'knows' that they are external, as the have an 'external' class attached.

It would be nice if those external links are visible as is, via one of those small 'external link' icons behind them.

So if sphinx is not able (plz verify) we could use some jquery magic, like written here:
http://css-tricks.com/snippets/jquery/open-external-links-in-new-window/
and apply those to all links which have class external

Implement 'Learn about QGIS' Page

Start with RST, perhaps add styling, maybe move to custom html?

Make screenshots page a carousel with text snippets

Make download button in header a button?

This should be very prominent right away in the home page.

Fix images in commercial support page

Rewrite About/Discover page

http://new.qgis.org/html/en/about/index.html

This page should start off with what qgis is, what features it has and what it can do for the user rather than its Open Source Bona Fides.

Body Offsets with fixed header and footer

Implement User & Developer 'tours'

ala http://geonode.org/user_features.html and http://geonode.org/dev_features.html but with screenshots mixed in.

Anchors untranslated?

AFAIK, anchors (internal links in the page) are not translated. So in translated pages, internal links will remain in English. This may or may not be a problem, it should be taken into account.

Add Sponsors to footer using snippet template

The sponsors can be shown at all times in the footer. This may not contain all sponsors, but new and big ones and a link to all of them. This should be able to be optionally included by using a snippet template.

Update readme with complete instructions (including virtualenv)

language dropdown should be able to show utf: 中文

The language dropdown should show the language in the language itself. So for eg:
dutch: nederlands
chinese: 中文
spanish: Español

We have to be sure that we can handle this utf-8 kind of languages, both in content and in site strings.

(question: should we or not also do the language in english? Or will the values then just be too long:
Nederlands (dutch)
Español (spanish)
中文 (chinese) etc

Maybe just start with the real strings. Later we can make it really dynamic: like if you are in dutch, show:
Nederlands (nederlands)
Español (spaans)
中文 (chinees) etc

Make sure search is properly setup for i18n

Implement 'custom' html splash page

Change front page text

per @timlinux

"A Geographic Information System allows you to create, edit, visualise, analyse and report on geospatial information."

Add a map to commercial support page

"Commerical Support in Your Region/Country"

Add content to developers page

http://new.qgis.org/html/en/development/index.html

Consider having the home page carousel show off features themselves and not maps

Think apple product websites, they always show you the three coolest or most relevant features before going into other detail.

Page menus on the side of the page

not on top menu

Merge mailing lists to community page, add content and layout

There should be a single page that is the launching off point to many aspects of the community. This page probably requires some custom layout, but we should just make it a complete set of resource in rst initially.

Remove Previous and Next links

Previous and Next links should be removed from top menu (useful for manuals, not for a website)

Not able to override existing images or add new ones

The directory I am using is: source/website/static/website/images.

menu doesn't work with github banner on mobile

Can't click on menu on mobile (iPhone) because github ribbon is in the way.

Not able to override sphinx css file import

Sphinx theme includes one css file that I'd like to drop and not use at all. I am able to import custom css files, but I can't override the existing ones. Basically, how can I do the following: do not include this css file.

Add 'social' links in the footer

• Twitter
• Mailing Lists
• Blog
• Planet
• Google+?
• Others?

Replace Quantum GIS with QGIS

ensure responsive layouts in common mobile devices

Barely usable on my iPhone, better on iPad, untested on android.

Add links to switch between $lang

Perhaps with a list of flags

Homepage contains extra content that got added automatically

I had to override the layout of the homepage, so I used page.html template. Not sure what I am doing wrong but I see extra content on the homepage. Here's what I currently have in page.html:

{% extends "layout.html" %}
{%- block content %}
{{ qgis_navBar() }}
{% if pagename == 'index' %}
{% include 'index.html' %}
{% endif %}

{% block body %}
    {% if pagename == 'forusers/index' %}
        {% include 'forusers_index.html' %}
    {% elif pagename == 'forusers/download' %}
        {% include 'forusers_download.html' %}
    {% elif pagename == 'getinvolved/index' %}
        {% include 'getinvolved_index.html' %}
    {% elif pagename == 'about/index' %}
        {% include 'about_index.html' %}
    {% else %}
        {{ body }}
    {% endif %}
{% endblock %}

{%- endblock %}

Fix logo overlap in header

Update 'Get Involved' Page and add light styling

• mailinglist
• compile howtos
• IRC
• python developement & plugins
• api docs etc etc
• wiki
• release
• hub.qgis.org
• translation etc etc

See http://www.flickr.com/photos/97361298@N07/9603909791/lightbox/

Multiple includes of bootstrap-2.3.2.js in header

Multiple includes of bootstrap-2.3.2.js in header right now, causes a console error

view-source:http://new.qgis.org/html/en/site/index.html

Enhance Case Studies page with snippets and screenshots

ala http://geonode.org/gallery/

Full TOC in sidebar not usable on small screens

If we have a TOC with a lot of items, eg:
http://new.qgis.org/html/nl/getinvolved/development/pyqgis_developer_cookbook/index.html
You will not be able to see/use the lowest items of the toc, because the sidebar is used.

If people agree that the sidebar should scroll:

That is an easy fix, it is now fixed to the top, but if we take out the affix class from the sidebar div, it will scroll:

becomes

Implement submenus in header -and/or- side slideout menu

choose language based on current locale of browser AND remember it

in the old website, you always started with english language. A nice feature would be (often asked, and seems not so difficult to do) is to set the language based on the current locale of the language browser used.

BUT if we do that, I think it would be a nice addition if we write a little cookie also, which sets the last used locale. So a chinese person working for an english company, using an english browser, will start with english only the first time. But after choosing chinese for one time, all other times the cookie is read and he starts in chinese.
So the cookie should remember last used language.

Detect platform and show appropriate download link by default

The download page should auto-detect your platform from the UserAgent string and present the best download option most prominently.

Google does a very good job of this in my experience.

Search case should be on the same block as the menus

In the current setting, resizing the browser window brings the Search on a lower row, thus breaking the layout. It should move together with the menu, as in standard theme.

QGIS Core Text

On this page: http://new.qgis.org/html/en/site/getinvolved/index.html

The paragraph about QGIS Core talks only about core plugins, but core development is to a big part not related to core plugins but to the core libraries and application.

Implement carousel with images from flickr gallery (include div with description and link)

Current carousel is just a test.

Implement 'below the fold' elements

• Nav (Developers, Questions?, QGIS News, Contribute, Commercial Support)
• Tutorials Snippets
• Case Studies Snippets
• Tweet snippets?
• Upcoming Events Snippets
• Books and things?

Custom css file gets imported before the default sphinx file instead of after

As a temporary workaround I added !important declaration in the custom less file. These declarations have to be removed, once the issue is fixed.

Top menu should be on a row

searchbox error and looking different in several browsers

In Firefox the searchbox (select) also shows the native dropdown arrows.

Besides this the box looks different in all browsers, not sure what is the preferred look.

Implement 'Learn about QGIS' Page

Start with RST, perhaps add styling, maybe move to custom html?

We need to convey the fact that QGIS has Desktop, Server and Web Client offerings

Problem

The front page does not convey the fact that you can also use QGIS as a map server and a web client.

Proposed solution

• Replace download button with three boxes
• In the first box a picture of QGIS Desktop with a link to download underneath it
• In the second box, a graphic representing QGIS server with a link to installation procedure beneath it
• In the third box a picture of QGIS Web Client with a link beneath it to download

Expected outcome

A person arriving at the QGIS home page should understand that QGIS can be used in these three contexts and have starting points to using each

Add screencasts page

Implement 'custom' download page