Skip to content

qgis/QGIS-Website

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

QGIS Website

Screenshot

By Tim Sutton and QGIS Contributors.

Project Status

E2E Tests Deploy Hugo site to Pages Website Status License

Project stars: Stars

๐ŸƒBefore you start

This web site is a static site built using Hugo.

Hugo Logo and using the hugo bulma blocks theme.

๐Ÿ›’ Getting the Code

development

git clone https://github.com/qgis/QGIS-Website.git
cd QGIS-Website

๐Ÿง‘๐Ÿ’ป Development

First install hugo for your local machine:

๐Ÿ“ Note: we need to install the 'extended' hugo version which includes a SASS compiler. If you don't install the extended version you will get errors like this when compiling:

ERROR 2022/12/11 07:33:37 Rebuild failed: TOCSS: failed to transform 
"css/style.scss" (text/x-scss). Check your Hugo installation; you need 
the extended version to build SCSS/SASS.: this feature is not available 
in your current Hugo version, see https://goo.gl/YMrWcn for more information

Currently, the website requires Hugo with a minimum version of v0.139.0. Ensure you have a compatible version installed to avoid any build issues.

You can find the extended version v0.139.0 here.

Download

๐Ÿง Linux:

Download the latest version and then do

sudo dpkg -i hugo_extended_<latest>_linux-amd64.deb

๐Ÿ“ Note: if your system has another version of Hugo, no need to mess up with docker, snap, nix. Just extract the binaries somewhere with dpkg -x . Example, assuming that you use a dedicated directory for your local binaries :

mkdir -p ~/apps/hugo_139/
wget https://github.com/gohugoio/hugo/releases/download/v0.139.0/hugo_extended_0.139.3_linux-amd64.deb --output-document ~/apps/hugo_128/hugo_extended_0.139.3_linux-amd64.deb 
dpkg -x hugo_extended_0.139.3_linux-amd64.deb
~/apps/hugo_128/usr/local/bin/hugo server  

๐ŸชŸ Windows

Follow these notes

๐Ÿ macOS:

Follow these notes

โš™๏ธ Setting up VSCode

If you are using VSCode, I recommend the following extensions:

  • Hugo Language and Syntax Support
  • Color Highlight

Clone the repo:

git clone https://github.com/qgis/QGIS-Website.git

Run the site:

Press Ctl-Shift-D then choose the following runner:

'Run dev using locally installed Hugo'

the click the green triangle next to the runner to start it.

Once the site is running, you can open it at:

http://localhost:1313

The site will automatically refresh any page you have open if you edit it and save your work. Magical eh?

Run in other IDEs

Use an appropriate Hugo plugin for your IDE, or run Hugo frรฅn the command line:

hugo server

You can then visit the hot-reloaded site in your browser at http://localhost:1313/

Running Playwright End to End (e2e) Tests

Test files are located in playwright/ci-test/tests.

These tests exist to make sure code changes to this repository do not break how the site currently functions. They are intended to run on each commit to verify the site is working in the expected order.

Run tests with VSCode

Requirements: NodeJS v18+

  1. Install playwright: If you haven't already installed Playwright, you can do so by running the following commands in playwright/ci-test directory.
cd playwright/ci-test
npm install
  1. Install playwright browsers:
npx playwright install --with-deps chromium
  1. Install the extension Playwright Test for VSCode: This extension provides a seamless integration of Playwright testing into VSCode.

Screenshot

  1. Open the Testing Tab: In VSCode, click on the Testing icon in the Activity Bar on the side of the window. This will open the Testing tab.

  2. Run Playwright Tests from the Testing Tab:

  • In the Testing tab, you should see your Playwright tests listed. If not, ensure the browser is checked under Playwright > Project menu.
  • Click on the refresh button in the Testing tab to reload the tests.
  • You can run individual tests by clicking the play button next to the test name.
  • You can also run all tests by clicking the play button at the top of the Testing tab.

Screenshot

  1. Debugging Tests:
  • You can debug individual tests by clicking the debug icon (a small bug with a play button) next to the test name.
  • Make sure to set breakpoints in your test files before running the debugger.

Run tests with CLI

By default, this will run in headless mode just as it is in CI.

./run-tests.sh

NOTE: To run it in UI mode, add the --ui tag to the script.

$PLAYWRIGHT \
    test \
    --ui \
    --project chromium

Read more on testing here.

Running as github action

There is a github action that will run the tests automatically on PR submission, merge.

See .github/workflows/playwright-e2e.yml

Content Harvesting

You can harvest data from various feeds using the fetch_feeds.py script. By default flickr harvesting is disabled in this script so run it manually and review the content to see if it is suitable for publication on our site.

./fetch_feeds.py --flickr=yes

Flickr parsing creates new files and md pages with param draft: true. It can be changed to false after manual verification. The script will not overwrite the changes. Pictures with draft: false will appear on /project/overview/maps/ and /project/overview/screenshots/.

This script is run nightly as a github action (see .github/workflows/update-feeds.yml).

Search Functionality

The search functionality uses both FuseJS and MarkJS.

The search functionality code is based on this Blog Post and GitHub Gist by Eddie Webb.

Content folders need to be excluded from search, by making them headless bundles - which we have done for the sustaining member and flagship user folders in content/. To make other content folders which are not rendered and included in search results, add an index.md file with the following content: headless = true.

Referencing URLs in templates

The site needs to work in production, where the links of the site are all below the root URL, and in staging, where the site is deployed to GitHub pages in a subpath. To ensure both deployment strategies work, please use the following method of constructing URLs in templates.

<a class="button is-primary" href="{{ "donate/" | absURL }}">

Note: We do not use a leading slash, only an ending slash.

Styles (SASS/CSS)

SASS for most components is stored in themes/hugo-bulma-blocks-theme/assets/sass/bulma/components/

Some common styles are places in themes/hugo-bulma-blocks-theme/assets/sass/style.sass - this file is compiled as hugo template, hence has access to config.toml variables and hugo macroses

Also some bulma theme overrides are placed in themes/hugo-bulma-blocks-theme/assets/css/custom.css

๐Ÿ“ File naming conventions

  • Separate words in file names with hyphens e.g. windows-download.md
  • Avoid abbreviations in the words of your files
  • Write file names in lower case only
  • No spaces in file names

๐Ÿค Contributing to this project

We welcome your contributions! All contributors are expected to sign a contributor license agreement (CLA) which you can see here. This process is automatically enabled when you create your first pull request via https://cla-assistant.io/.

CLA assistant

๐Ÿ’ฎ Changing the templates

Page type Path
Landing Page themes/qgis/layouts/index.html
Top Level Pages themes/qgis/layouts/_default/single.html

๐Ÿ  Editing the landing (home) page

The layout of the landing page is themes/hugo-bulma-blocks-theme/layouts/index.html: the main page has many diverse blocks, that are not used anywhere else, hence its content is mostly in the partials.

The content/_index.md contains the front matter of the page and the contents for the feature shortcodes. Just edit whatever you like there. The blocks shortcodes are described here

๐Ÿ“ƒ Adding a top level page

Create the content

Content pages are stored in the content folder. The top level documents there will be rendered with the top level page theming.

For example to add an about page, create content/about.md

The page will be accessible then at /about/

๐Ÿ–ผ๏ธ Referencing Images and Media

Place images and media in static/img. Everything in static is referenced from the top level of the site e.g. static/img/foo.png would be referenced in markdown as /img/foo.png.

๐Ÿ“ฆ Blocks Shortcodes

The site uses a number of shortcodes to create reusable blocks of content. These are defined in the themes/hugo-bulma-blocks-theme/layouts/shortcodes/ folder.

The shortcodes with screenshots are described here

Reusable header web component

TODO

Sidebar

Sidebar is implemented in themes/hugo-bulma-blocks-theme/layouts/partials/sidebar.html

Items are retrieved from config.toml under [menu] section. weight parameter defines the order of the item.

To enable sidebar on the content page, use the following template:

---
type: "page"
...
sidebar: true
---
{{< content-start  >}}

... add content here ...

{{< content-end  >}}

LT/LTR release variables

Script for parsing release schedule from the google spreadsheet is scripts/update-schedule.py. It creates data/conf.json with variables that can be used later in md/html.

Script for harvesting the visualchangelog from changelog.qgis.org is scripts/changelog_harvest.py. It will create/update a visual-changelogs at content/project/visual-changelogs based on the data at data/conf.json.

Usage:

$ ./scripts/changelog_harvest.py

# For a specific version
$ ./scripts/changelog_harvest.py --version 3.34 --release 21.06.2024

Example usage in md:

Here you will simply install the latest stable QGIS ({{< param "version" >}}.x {{< param "codename" >}}) 

To include param as link, use param-link shortcode: it correctly renders as md link, and not as plain text

Electronic document: {{< param-link "userguidecite" >}}

Example usage in HTML:

to use params inside shortcode or partial, use wrapper:

{{ with index .Site.Data.conf }}
...
<a
	class="button is-primary1 mb-3"
	href="{{ .ltr_msi }}"
	onclick="thanks(this)"
	download
>Long Term Version for Windows ({{ .ltrversion }} {{ .ltrnote }})</a>

{{ end }}

Example usage as shortcode param:

tricky part: shortcodes can't be used as other shortcodes' params. So you need to make replacement in the outer shortcode: "tabs.html" make a replacement of |ltrversion| and |version| to the values from config.

{{< tabs tab1="QGIS |ltrversion|" tab2="QGIS |version|" tab3="QGIS testing (>|ltrversion|)" tab4="Archived releases">}}

URL mapping from old site structure

This table represents required redirects from old URL structure to the new one: https://docs.google.com/spreadsheets/d/12Oo761Zwgj4iLeJxdrg8I31rGzsB95z5M1PpW9pYma8/edit?usp=sharing

Notes:

  • it will be more convenient to store all redirects in same file (nginx conf or else)
  • hugo aliases not recommended: they work, but don't support regex. also hard to maintain: redirects are spread across content files
  • use regexps to redirect from all langs
  • use regexps to map between similar stuff (case studies, visual changelog) - example rewrite rules below

Bulk redirects can be done like

map $url $new_url {
	...
    ^/[A-Za-z-]+/site/about/case_studies/(.*).html /project/case-studies/$1/;
    ^/[A-Za-z-]+/site/forusers/visualchangelog(.*)/index.html /project/visual-changelogs/visualchangelog$1/;
	^/[A-Za-z-]+/site/forusers/usergroups.html /community/organisation/groups/;
	...
}

See nginx map tutorial and examples with regex capture

Stripe donations

main donation page: https://qgis.github.io/QGIS-Website/funding/donate/

Stripe widget can be included to any page with the shortcode {{<stripe-widget>}}

Payment options are implemented with Payment Links. Values and links can be updated in data/stripe_products.yml

Note: payment links also support recurring donations (subscriptions) - products with recurrent payments should be created for that matter

Donors scraping

Is not ported yet. Donors are stored in data/donors.json. adddonor.pl and related scripts & webhooks should be adapted to the new format

Auto-checking for broken links

docker run --rm dcycle/broken-link-checker:3 https://qgis.github.io/QGIS-Website > broken_links.csv

Crawls the site and reports all 404. Full run takes apout 10 mins