# SPDX-FileCopyrightText: 2017-2022 CERN and the Allpix Squared authors
# SPDX-License-Identifier: CC-BY-4.0
Allpix Squared Website
This repository contains the static website pages of the Allpix Squared project. The deployed website can be found here.
All commits to the master branch of this repository are automatically deployed via GitLab pages and thus directly reflect on the published website.
Dependencies
The website is generated from markdown files using the hugo compiler written in Go. In order to
install Hugo on your machine, pick the appropriate package or binary from
the latest release. Since we use
hugo modules, one also needs the go
binary, which can be downloaded
here.
Commands
The following commands might help adding content and testing the website locally before committing and deployment:
-
Start a local test server
./get_artifacts.sh ref # fetches the docs from the main repo hugo server -D
The server will listen to http://localhost:1313/. The additional command line argument
-D
also enables all documents currently in draft mode.If you want to test changes e.g. for a merge request, you can either supply a reference to your branch like this:
./get_artifacts.sh ref branch_name user_name/repo_name # default: master allpix-squared/allpix-squared
However this might not work if your pipeline is failing. To select artifacts from a specific job, use this:
./get_artifacts.sh job job_nr # you can find job_nr in the URL of the specific docs:usermanual-hugo job
Note: in both cases the repository has to be hosted on the CERN GitLab instance for the CI to work.
-
Add a new page In order to add a new static page, run
hugo new content/pagetitle.md
and a new markdown file with the appropriate header will be created. The draft status is set to
true
by default. -
Add a new post to the blog roll In order to add a new post to the blog/new roll, run
hugo new content/post/YYYY-MM-DD-post-title.md
and a new markdown file with the appropriate header will be created. The draft status is set to
true
by default. For releases, changenews
toreleases
. Make sure to add a properly formatted date in your filename. -
Add page to the main menu
See for example content/docs/_index.md how to define a page to be in the main menu.
-
Test API reference To test the website with the API reference, download it via
./get_artifacts.sh ref doxy # fetches the API reference from the main repo
or
./get_artifacts.sh job doxy job_nr # fetches the API reference for a specific CI job
Deploy Changes
Simply push to the master
branch of this repository to get things published. It should be noted that only documents with
draft = false
will be included in the published website.
Updating Docsy & Prism
-
Docsy To update Docsy (our hugo theme), run
hugo mod get -u
Note: updating might require changes in the
layouts/post
folder, which is derived from the upstreamlayouts/blog
folder. The currently used version is v0.7.0 from June 2023. -
Prism To update Prism (our code highlighter), visit this page and download
prism.js
andprism.css
to thestatic/js
andstatic/css
folder respectively. Note that if you change any settings, make sure to update this README with the corresponding URL as well. The currently used version is 1.29.0 from August 2022. -
Roboto Roboto is the main font for the website. It is usually included via Google Fonts, however we want to avoid pinging Google Servers for legal reason, thus the font is self-hosted and needs to be updated from time to time. To update the fonts, visit this page and select
latin
,latin-ext
,greek
,greek-ext
with font size300
,regular
,500
,700
,300italic
,italic
,500italic
,700italic
in theModern Browsers
format. Then copy the.woff2
files tostatic/webfonts
. The currently used version is v30. -
Font Awesome Font Awesome is self-hosted, so it needs to be updated from time to time. Use the "Free For Web" download from here and copy the
.woff2
files tostatic/webfonts
. The currently used version is v6.4.0 from March 2023.
CERN webEOS setup
This is a more technical section mainly interesting for developers documenting the setup of the website.
The main website is deployed via GitLab pages, as documented in how-to.docs.cern.ch. The
project name on webEOS (webeos.cern.ch) is allpix-squared
and it is managed by the
cernbox-project-allpix-squared-admins
eGroup. It only is used by the "Gitlab Pages Site Operator" to publish the hugo
generated page to allpix-squared.docs.cern.ch.
The old website was hosted on project-allpix-squared.cern.ch, with the project
name project-allpix-squared
on webEOS. It is still used in the deploy:eos
job in the main repo to deploy the PDF
documentation to project-allpix-squared.web.cern.ch/usermanual.
If one is member of the cernbox-project-allpix-squared-admins
eGroup that manages project-allpix-squared.web.cern.ch
,
the webroot can be accessed via CERNBox (Your Projects -> allpix-squared -> www).
To ensure links to the old website still work fine, redirects have been created using these HTML headers:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0; url='https://allpix-squared.docs.cern.ch/post/some-news-entry/'" />
</head>
</html>