initial testing with Zensical

This commit is a test run, currently I would stick with MM proper until
Zensical is more mature. Hopefully in about half a year.

Missing features:
- blog for news articles (using template at the moment, not ideal)

.vscode/settings.json

@@ -1,6 +0,0 @@
-// Place your settings in this file to overwrite default and user settings.
-{
-  "files.associations": {
-    "*.html": "liquid"
-  }
-}

Dockerfile

@@ -1,4 +0,0 @@
-FROM docker.io/squidfunk/mkdocs-material:9.7
-
-# add some plugins
-RUN pip install mkdocs-glightbox=='0.5.*'

compose.yml

@@ -1,9 +1,8 @@
 ---
 services:
-  mkdocs:
+  zensical:
-    build: .
+    image: docker.io/zensical/zensical:latest
-    # explicitly force live-reloading per https://github.com/squidfunk/mkdocs-material/issues/8478
+    command: serve --dev-addr=0.0.0.0:8000
-    command: serve --dev-addr=0.0.0.0:8000 --livereload
     security_opt:
       - no-new-privileges:true
     volumes:

docs/merlin6/index.md

@@ -3,7 +3,7 @@
 ## Slurm clusters
 
 * The new Slurm CPU cluster is called **`merlin6`**.
-* The new Slurm GPU cluster is called [**`gmerlin6`**](../gmerlin6/cluster-introduction.md)
+* The new Slurm GPU cluster is called [**`gmerlin6`**](gmerlin6/cluster-introduction.md)
 * The old Slurm *merlin* cluster is still active and best effort support is provided.
 
 The cluster, was renamed as [**merlin5**](../merlin5/cluster-introduction.md).

docs/merlin6/quick-start-guide/accessing-slurm.md

@@ -34,7 +34,7 @@ For further information about how to use this cluster, please visit: [**Merlin6
 
 The **Merlin6 GPU cluster** (**`gmerlin6`**) is visible from the login nodes. However, to submit jobs to this cluster, one needs to specify the option `--cluster=gmerlin6` when submitting a job or allocation.
 
-For further information about how to use this cluster, please visit: [**Merlin6 GPU Slurm Cluster documentation**](../../gmerlin6/slurm-configuration.md).
+For further information about how to use this cluster, please visit: [**Merlin6 GPU Slurm Cluster documentation**](../gmerlin6/slurm-configuration.md).
 
 ### Merlin5 CPU cluster access
 

docs/merlin6/quick-start-guide/introduction.md

@@ -43,7 +43,7 @@ These computational resources are split into **two** different **[Slurm](https:/
 
 * The Merlin6 CPU nodes are in a dedicated **[Slurm](https://slurm.schedmd.com/overview.html)** cluster called [**`merlin6`**](../slurm-configuration.md).
     * This is the **default Slurm cluster** configured in the login nodes: any job submitted without the option `--cluster` will be submited to this cluster.
-* The Merlin6 GPU resources are in a dedicated **[Slurm](https://slurm.schedmd.com/overview.html)** cluster called [**`gmerlin6`**](../../gmerlin6/slurm-configuration.md).
+* The Merlin6 GPU resources are in a dedicated **[Slurm](https://slurm.schedmd.com/overview.html)** cluster called [**`gmerlin6`**](../gmerlin6/slurm-configuration.md).
     * Users submitting to the **`gmerlin6`** GPU cluster need to specify the option ``--cluster=gmerlin6``.
 
 ### Merlin5

docs/merlin6/slurm-general-docs/running-jobs.md

@@ -52,7 +52,11 @@ The following settings are the minimum required for running a job in the Merlin
   #SBATCH --clusters=<cluster_name>     # Possible values: merlin5, merlin6, gmerlin6
   ```
 
-  Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information.
+  Refer to the documentation of each cluster
+  [**`merlin6`**](../slurm-configuration.md),
+  [**`gmerlin6`**](../gmerlin6/slurm-configuration.md),
+  [**`merlin5`**](../../merlin5/slurm-configuration.md) for further
+  information.
 
 * **Partitions:** except when using the *default* partition for each cluster, one needs to specify the partition:
 
@@ -60,7 +64,11 @@ The following settings are the minimum required for running a job in the Merlin
   #SBATCH --partition=<partition_name>  # Check each cluster documentation for possible values
   ```
 
-  Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information.
+  Refer to the documentation of each cluster
+  [**`merlin6`**](../slurm-configuration.md),
+  [**`gmerlin6`**](../gmerlin6/slurm-configuration.md),
+  [**`merlin5`**](../../merlin5/slurm-configuration.md) for further
+  information.
 
 * **[Optional] Disabling shared nodes**: by default, nodes are not exclusive. Hence, multiple users can run in the same node.  One can request exclusive node usage with the following option:
 
@@ -74,7 +82,11 @@ The following settings are the minimum required for running a job in the Merlin
    #SBATCH --time=<D-HH:MM:SS>          # Can not exceed the partition `MaxTime`
    ```
 
-  Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information about partition `MaxTime` values.
+  Refer to the documentation of each cluster
+  [**`merlin6`**](../slurm-configuration.md),
+  [**`gmerlin6`**](../gmerlin6/slurm-configuration.md),
+  [**`merlin5`**](../../merlin5/slurm-configuration.md) for further information
+  about partition `MaxTime` values.
 
 * **Output and error files**: by default, Slurm script will generate standard output (`slurm-%j.out`, where `%j` is the job_id) and error (`slurm-%j.err`, where `%j` is the job_id) files in the directory from where the job was submitted. Users can change default name with the following options:
 
@@ -92,8 +104,14 @@ The following settings are the minimum required for running a job in the Merlin
   #SBATCH --hint=nomultithread          # Don't use extra threads with in-core multi-threading.
   ```
 
-  Refer to the documentation of each cluster ([**`merlin6`**](../slurm-configuration.md),[**`gmerlin6`**](../../gmerlin6/slurm-configuration.md),[**`merlin5`**](../../merlin5/slurm-configuration.md) for further information about node configuration and Hyper-Threading.
+  Refer to the documentation of each cluster
-  Consider that, sometimes, depending on your job requirements, you might need also to setup how many `--ntasks-per-core` or `--cpus-per-task` (even other options) in addition to the `--hint` command. Please, contact us in case of doubts.
+  ([**`merlin6`**](../slurm-configuration.md),
+  [**`gmerlin6`**](../gmerlin6/slurm-configuration.md),
+  [**`merlin5`**](../../merlin5/slurm-configuration.md) for further information
+  about node configuration and Hyper-Threading.  Consider that, sometimes,
+  depending on your job requirements, you might need also to setup how many
+  `--ntasks-per-core` or `--cpus-per-task` (even other options) in addition to
+  the `--hint` command. Please, contact us in case of doubts.
 
   !!! tip
       In general, for the cluster `merlin6` <span

docs/news/index.md

@@ -1,2 +0,0 @@
-# News
-

docs/news/launching-merlin6-docs.md

@@ -1,12 +1,9 @@
 ---
-date:
+title: "Merlin 6 documentation available"
-  created: 2019-06-12
+date: "12 June 2019"
-tags:
+template: "news.html"
-  - getting_started
 ---
 
-# Merlin 6 documentation available
-
 Merlin 6 docs are now available at [Merlin6 docs](../../merlin6/index.md)!
 
 More complete documentation will be coming shortly.

docs/news/merlin7-preprod-docs.md

@@ -1,12 +1,9 @@
 ---
-date:
+title: "Merlin7 in preproduction"
-  created: 2024-08-07
+date: "7 August 2024"
-tags:
+template: "news.html"
-  - getting_started
 ---
 
-# Merlin7 in preproduction
-
 The Merlin7 cluster is officially in preproduction. This phase will be tested by a few users
 and slowly we will contact other users to be part of it. Keep in mind that access is restricted.
 

overrides/news.html

@@ -0,0 +1,24 @@
+{% extends "base.html" %}
+
+{# this document is based on the offical template as given in 
+   https://github.com/zensical/ui/blob/master/src/base.html. #}
+
+{% block container %}
+	<div class="md-content" data-md-component="content">
+
+		<!-- Navigation path (breadcrumbs) -->
+		{% if "navigation.path" in features %}
+			{% include "partials/path.html" %}
+		{% endif %}
+
+		<!-- Page content -->
+		<article class="md-content__inner md-typeset">
+			{% if page.meta and page.meta.date %}
+			<div class="md-post__meta md-meta">{{ page.meta.date }}</div>
+			{% endif %}
+			{% block content %}
+				{% include "partials/content.html" %}
+			{% endblock %}
+		</article>
+	</div>
+{% endblock %}

zensical.toml

@@ -0,0 +1,290 @@
+[project]
+site_name = "HPCE User Documentation"
+site_description = "Documentation of the computing resources managed by the HPCE group"
+site_author = "HPCE Group"
+site_url = "https://hpce.pages.psi.ch"
+copyright = """
+Copyright © 2025 HPC and Emerging Technologies Group/CSD @ Paul Scherrer Institut
+"""
+
+# Repository
+repo_url = "https://gitea.psi.ch/hpce/gitea-pages"
+repo_name = "userdocs"
+# TODO unsure if this works, branch needs to be changed from `mkdocs` to `main`
+edit_uri = "_edit/mkdocs/docs/"
+
+# Zensical supports both implicit navigation and explicitly defined navigation.
+# If you decide not to define a navigation here then Zensical will simply
+# derive the navigation structure from the directory structure of your
+# "docs_dir". The definition below demonstrates how a navigation structure
+# can be defined using TOML syntax.
+#
+# Read more: https://zensical.org/docs/setup/navigation/
+# nav = [
+#   { "Get started" = "index.md" },
+#   { "Markdown in 5min" = "markdown.md" },
+# ]
+
+# With the "extra_css" option you can add your own CSS styling to customize
+# your Zensical project according to your needs. You can add any number of
+# CSS files.
+#
+# The path provided should be relative to the "docs_dir".
+#
+# Read more: https://zensical.org/docs/customization/#additional-css
+#
+#extra_css = ["stylesheets/extra.css"]
+
+# With the `extra_javascript` option you can add your own JavaScript to your
+# project to customize the behavior according to your needs.
+#
+# The path provided should be relative to the "docs_dir".
+#
+# Read more: https://zensical.org/docs/customization/#additional-javascript
+#extra_javascript = ["javascripts/extra.js"]
+
+# ----------------------------------------------------------------------------
+# Section for configuring theme options
+# ----------------------------------------------------------------------------
+[project.theme]
+variant = "modern"
+
+# Zensical allows you to override specific blocks, partials, or whole
+# templates as well as to define your own templates. To do this, uncomment
+# the custom_dir setting below and set it to a directory in which you
+# keep your template overrides.
+#
+# Read more:
+# - https://zensical.org/docs/customization/#extending-the-theme
+#
+custom_dir = "overrides"
+
+favicon = "images/favicon.ico"
+logo = "images/hpce_logo.png"
+
+# Zensical supports more than 60 different languages. This means that the
+# labels and tooltips that Zensical's templates produce are translated.
+# The "language" option allows you to set the language used. This language
+# is also indicated in the HTML head element to help with accessibility
+# and guide search engines and translation tools.
+#
+# The default language is "en" (English). It is possible to create
+# sites with multiple languages and configure a language selector. See
+# the documentation for details.
+#
+# Read more:
+# - https://zensical.org/docs/setup/language/
+#
+language = "en"
+
+# Zensical provides a number of feature toggles that change the behavior
+# of the documentation site.
+features = [
+    # Zensical includes an announcement bar. This feature allows users to
+    # dismiss it then they have read the announcement.
+    # https://zensical.org/docs/setup/header/#announcement-bar
+    "announce.dismiss",
+
+    # If you have a repository configured and turn on this feature, Zensical
+    # will generate an edit button for the page. This works for common
+    # repository hosting services.
+    # https://zensical.org/docs/setup/repository/#code-actions
+    "content.action.edit",
+
+    # If you have a repository configured and turn on this feature, Zensical
+    # will generate a button that allows the user to view the Markdown
+    # code for the current page.
+    # https://zensical.org/docs/setup/repository/#code-actions
+    "content.action.view",
+
+    # Code annotations allow you to add an icon with a tooltip to your
+    # code blocks to provide explanations at crucial points.
+    # https://zensical.org/docs/authoring/code-blocks/#code-annotations
+    "content.code.annotate",
+
+    # This feature turns on a button in code blocks that allow users to
+    # copy the content to their clipboard without first selecting it.
+    # https://zensical.org/docs/authoring/code-blocks/#code-copy-button
+    "content.code.copy",
+
+    # Code blocks can include a button to allow for the selection of line
+    # ranges by the user.
+    # https://zensical.org/docs/authoring/code-blocks/#code-selection-button
+    "content.code.select",
+
+    # Zensical can render footnotes as inline tooltips, so the user can read
+    # the footnote without leaving the context of the document.
+    # https://zensical.org/docs/authoring/footnotes/#footnote-tooltips
+    "content.footnote.tooltips",
+
+    # If you have many content tabs that have the same titles (e.g., "Python",
+    # "JavaScript", "Cobol"), this feature causes all of them to switch to
+    # at the same time when the user chooses their language in one.
+    # https://zensical.org/docs/authoring/content-tabs/#linked-content-tabs
+    "content.tabs.link",
+
+    # TODO: not sure I understand this one? Is there a demo of this in the docs?
+    # https://zensical.org/docs/authoring/tooltips/#improved-tooltips
+    "content.tooltips",
+
+    # With this feature enabled, Zensical will automatically hide parts
+    # of the header when the user scrolls past a certain point.
+    # https://zensical.org/docs/setup/header/#automatic-hiding
+    # "header.autohide",
+
+    # Turn on this feature to expand all collapsible sections in the
+    # navigation sidebar by default.
+    # https://zensical.org/docs/setup/navigation/#navigation-expansion
+    # "navigation.expand",
+
+    # This feature turns on navigation elements in the footer that allow the
+    # user to navigate to a next or previous page.
+    # https://zensical.org/docs/setup/footer/#navigation
+    "navigation.footer",
+
+    # When section index pages are enabled, documents can be directly attached
+    # to sections, which is particularly useful for providing overview pages.
+    # https://zensical.org/docs/setup/navigation/#section-index-pages
+    "navigation.indexes",
+
+    # When instant navigation is enabled, clicks on all internal links will be
+    # intercepted and dispatched via XHR without fully reloading the page.
+    # https://zensical.org/docs/setup/navigation/#instant-navigation
+    "navigation.instant",
+
+    # With instant prefetching, your site will start to fetch a page once the
+    # user hovers over a link. This will reduce the perceived loading time
+    # for the user.
+    # https://zensical.org/docs/setup/navigation/#instant-prefetching
+    "navigation.instant.prefetch",
+
+    # In order to provide a better user experience on slow connections when
+    # using instant navigation, a progress indicator can be enabled.
+    # https://zensical.org/docs/setup/navigation/#progress-indicator
+    #"navigation.instant.progress",
+
+    # When navigation paths are activated, a breadcrumb navigation is rendered
+    # above the title of each page
+    # https://zensical.org/docs/setup/navigation/#navigation-path
+    "navigation.path",
+
+    # When pruning is enabled, only the visible navigation items are included
+    # in the rendered HTML, reducing the size of the built site by 33% or more.
+    # https://zensical.org/docs/setup/navigation/#navigation-pruning
+    #"navigation.prune",
+
+    # When sections are enabled, top-level sections are rendered as groups in
+    # the sidebar for viewports above 1220px, but remain as-is on mobile.
+    # https://zensical.org/docs/setup/navigation/#navigation-sections
+    "navigation.sections",
+
+    # When tabs are enabled, top-level sections are rendered in a menu layer
+    # below the header for viewports above 1220px, but remain as-is on mobile.
+    # https://zensical.org/docs/setup/navigation/#navigation-tabs
+    "navigation.tabs",
+
+    # When sticky tabs are enabled, navigation tabs will lock below the header
+    # and always remain visible when scrolling down.
+    # https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs
+    "navigation.tabs.sticky",
+
+    # A back-to-top button can be shown when the user, after scrolling down,
+    # starts to scroll up again.
+    # https://zensical.org/docs/setup/navigation/#back-to-top-button
+    "navigation.top",
+
+    # When anchor tracking is enabled, the URL in the address bar is
+    # automatically updated with the active anchor as highlighted in the table
+    # of contents.
+    # https://zensical.org/docs/setup/navigation/#anchor-tracking
+    "navigation.tracking",
+
+    # When search highlighting is enabled and a user clicks on a search result,
+    # Zensical will highlight all occurrences after following the link.
+    # https://zensical.org/docs/setup/search/#search-highlighting
+    "search.highlight",
+
+    # When anchor following for the table of contents is enabled, the sidebar
+    # is automatically scrolled so that the active anchor is always visible.
+    # https://zensical.org/docs/setup/navigation/#anchor-following
+    "toc.follow",
+
+    # When navigation integration for the table of contents is enabled, it is
+    # always rendered as part of the navigation sidebar on the left.
+    # https://zensical.org/docs/setup/navigation/#navigation-integration
+    #"toc.integrate",
+]
+
+# ----------------------------------------------------------------------------
+# In the "palette" subsection you can configure options for the color scheme.
+# You can configure different color # schemes, e.g., to turn on dark mode,
+# that the user can switch between. Each color scheme can be further
+# customized.
+#
+# Read more:
+# - https://zensical.org/docs/setup/colors/
+# ----------------------------------------------------------------------------
+[[project.theme.palette]]
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+# ----------------------------------------------------------------------------
+# In the "font" subsection you can configure the fonts used. By default, fonts
+# are loaded from Google Fonts, giving you a wide range of choices from a set
+# of suitably licensed fonts. There are options for a normal text font and for
+# a monospaced font used in code blocks.
+# ----------------------------------------------------------------------------
+#[project.theme.font]
+#text = "Inter"
+#code = "Jetbrains Mono"
+
+# ----------------------------------------------------------------------------
+# You can configure your own logo to be shown in the header using the "logo"
+# option in the "icons" subsection. The logo can be a path to a file in your
+# "docs_dir" or it can be a path to an icon.
+#
+# Likewise, you can customize the logo used for the repository section of the
+# header. Zensical derives the default logo for this from the repository URL.
+# See below...
+#
+# There are other icons you can customize. See the documentation for details.
+#
+# Read more:
+# - https://zensical.org/docs/setup/logo-and-icons
+# - https://zensical.org/docs/authoring/icons-emojis/#search
+# ----------------------------------------------------------------------------
+[project.theme.icon]
+#logo = "lucide/smile"
+#repo = "lucide/smile"
+
+# ----------------------------------------------------------------------------
+# The "extra" section contains miscellaneous settings.
+# ----------------------------------------------------------------------------
+#[[project.extra.social]]
+#icon = "fontawesome/brands/github"
+#link = "https://github.com/user/repo"
+
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.footnotes]
+[project.markdown_extensions.tables]
+[project.markdown_extensions.pymdownx.blocks.caption]
+[project.markdown_extensions.pymdownx.caret]
+[project.markdown_extensions.pymdownx.mark]
+[project.markdown_extensions.pymdownx.tilde]
+[project.markdown_extensions.pymdownx.details]
+[project.markdown_extensions.pymdownx.emoji]
+emoji_index = "zensical.extensions.emoji.twemoji"
+emoji_generator = "zensical.extensions.emoji.to_svg"
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+[project.markdown_extensions.pymdownx.inlinehilite]
+[project.markdown_extensions.pymdownx.snippets]
+[project.markdown_extensions.pymdownx.superfences]
+