Thank you for considering contributing to QGIS User Group India Website! We welcome contributions of all kinds, including bug fixes, feature requests, documentation improvements, and more. Please follow the guidelines below to ensure a smooth contribution process.
This web site is a static site built using Hugo.
and using the hugo bulma blocks theme.
To contribute, you need to clone the repository along with its submodules. The submodules contain the themes and shortcodes necessary to render the site.
Standard Clone:
git clone --recurse-submodules https://github.com/QGIS/QGIS-UG-India.git
cd QGIS-QGIS-UG-IndiaIf you have already cloned the repository without submodules:
git submodule update --init --recursive
For Nix based development environment, please skip directly to the Nix section.
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 informationCurrently, 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 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 Follow these notes We recommend using Windows Subsystem for Linux (WSL) for Hugo development on Windows instead of using Hugo packages for Windows.
This guide provides a step-by-step workflow to set up a local development environment for the QGIS website using Windows Subsystem for Linux (WSL) and the Hugo static site generator.
WSL allows you to run a Linux environment directly on Windows without the overhead of a traditional virtual machine. You can install WSL and the specific Ubuntu distribution in a single step.
-
Install Ubuntu 24.04 via WSL: Open PowerShell (as a standard user) and run:
wsl --install Ubuntu-24.04
-
Verify & Reboot: Check the status to ensure the subsystem is active:
wsl --statusNote: A system reboot is required after the initial installation to enable the necessary virtualization features.
Launch Ubuntu 24.04 from your Start Menu to complete the initial Linux user profile setup (username and password).
The QGIS website requires make for automation and the Hugo Extended binary for SCSS/SASS processing.
- Install Make: Update your package lists and install the make utility:
sudo apt update && sudo apt install make - Download Hugo (Extended Version):
- Check the latest version of Hugo at https://github.com/gohugoio/hugo/releases.
- From your Ubuntu terminal, download the extended version for your architecture (usually
amd64) usingwget:wget https://github.com/gohugoio/hugo/releases/download/v0.155.2/hugo_extended_0.155.2_linux-amd64.deb
- Install the downloaded package:
sudo dpkg -i hugo_extended_<version>_linux-amd64.deb
When working on a repository stored on your Windows file system (e.g., /mnt/c/Users/...), you may encounter errors during git clone or when Hugo tries to write to the disk. This is because WSL mounts Windows drives with different permission structures by default.
To fix this, you must remount the drive with metadata enabled. This allows Linux to manage file permissions and ownership correctly on the Windows drive.
- Unmount the C: Drive:
sudo umount /mnt/c
- Remount with Metadata:
sudo mount -t drvfs C: /mnt/c -o metadata
Note: With these permissions set, you can now navigate to your project folder and clone the repository without write errors.
Once the permissions are configured, you can clone the repository and use the built-in Makefile commands to start the local development server.
If you are contributing to the website after setting it up the first time, you must clone the repository recursively to ensure the theme and shortcode templates are included.
-
Navigate and Clone:
cd /mnt/c/Users/YourUsername/Documents git clone https://github.com/QGIS/QGIS-UG-India.git cd QGIS-UG-India
-
Navigate and Clone recursively:
cd /mnt/c/Users/YourUsername/Documents git clone --recurse-submodules https://github.com/QGIS/QGIS-UG-India.git cd QGIS-User-Group-Website
If you have already cloned without the submodules, run:
git submodule update --init --recursive
-
Run the Development Server: The QGIS repository uses
maketo simplify Hugo commands. Run the following to build the site and start the local server:make hugo-run-dev
Once the command finishes building, the website will usually be available at http://localhost:1313. Any changes you make to the files will automatically trigger a refresh in your browser.
Run the following command on this project root folder:
nix-shell # It will install all the dependecies
hugo server # To run the local server
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-UG-India.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:
The site will automatically refresh any page you have open if you edit it and save your work. Magical eh?
Use an appropriate Hugo plugin for your IDE, or run Hugo från the command line:
hugo serverYou can then visit the hot-reloaded site in your browser at http://localhost:1313/
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.
Requirements: NodeJS v18+
- Install playwright: If you haven't already installed Playwright, you can do so by running the following commands in
playwright/ci-testdirectory.
cd playwright/ci-test
npm install- Install playwright browsers:
npx playwright install --with-deps chromium-
Install the extension Playwright Test for VSCode: This extension provides a seamless integration of Playwright testing into VSCode.
-
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.
-
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.
- 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.
By default, this will run in headless mode just as it is in CI.
./run-tests.shNOTE: To run it in UI mode, add the --ui tag to the script.
$PLAYWRIGHT \
test \
--ui \
--project chromiumRead more on testing here.
There is a github action that will run the tests automatically on PR submission, merge.
See .github/workflows/playwright-e2e.yml
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.
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.
SASS for most components is stored in themes/qgis-website-theme/assets/sass/bulma/components/
Some common styles are places in themes/qgis-website-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/qgis-website-theme/assets/css/custom.css
- 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
| Page type | Path |
|---|---|
| Landing Page | themes/qgis/layouts/index.html |
| Top Level Pages | themes/qgis/layouts/_default/single.html |
The layout of the landing page is themes/qgis-website-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
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/
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.
The site uses a number of shortcodes to create reusable blocks of content. These are defined in the themes/qgis-website-theme/layouts/shortcodes/ folder.
The shortcodes with screenshots are described here
TODO
Sidebar is implemented in themes/qgis-website-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 >}}