mkdocs.yml

# ------------------------------------
# -------- Project Information -------
# ------------------------------------
site_name: NCAR HPC Documentation
site_description: NCAR HPC Docs website
repo_url: https://github.com/NCAR/HPC-Docs/
site_url: https://ncar-hpc-docs.readthedocs.io/en/latest/
site_author: CISL CSG (Consulting Services Group)
edit_uri: edit/main/docs/

# directories to watch for automatic rebuilding when running "mkdocs serve"
watch:
  - mkdocs.yml
  - themes/
  - docs/

# ------------------------------------
# -------- validation config ---------
# ------------------------------------
validation:
  nav:
    not_found: warn             # check if stubs exist or not!
    omitted_files: ignore       # check for files that exist without any links to them in nav
    absolute_links : warn       # check for absolute links -- pointers to outside htmls in nav

  links:
    not_found: ignore           # check for broken links inside mds. (to be activated later!)
    absolute_links : ignore     # check for absolute links -- pointers to outside htmls in files (to be activated later!)
    unrecognized_links: ignore  # unrecognized relative links (to be activated later!)

# ------------------------------------
# ----------- content ----------------
# ------------------------------------
nav:
  - Getting Started:
    - getting-started/index.md
    - End User Agreement: getting-started/end-user-agreement.md
    - Accounts:
      - getting-started/accounts/index.md
      - CIT Passwords: getting-started/accounts/cit-passwords.md
      - Duo Two-Factor Authentication:
        - getting-started/accounts/duo/index.md
        - Enrolling with Duo: getting-started/accounts/duo/enrolling.md
      - SAM: getting-started/accounts/systems-accounting-manager.md
    - Allocations:
      - allocations/index.md # -- https://arc.ucar.edu/knowledge_base/74317835
      - Managing Your Allocation: getting-started/managing-your-allocation.md
      - NCAR Allocations:
          - allocations/ncar-allocations/index.md
          - NCAR Strategic Capability (NSC) projects: allocations/ncar-allocations/ncar-strategic-capability-nsc-projects.md
      - University Allocations:
          - allocations/university-allocations/index.md
          - University Large Allocation Request Preparation Instructions : allocations/university-allocations/university-large-allocation-request-preparation-instructions.md
      - Determining computational resource needs: allocations/determining-computational-resource-needs.md
      - CISL HPC Allocations Panel:
          - allocations/chap/index.md
          - Allocation Review Criteria: allocations/chap/chap-allocation-review-criteria.md
          - Conflict of Interest Policy: allocations/chap/chap-conflict-of-interest-policy.md
  # -  HPC Quick Start: TODO CREATE PAGE
    - VPN access : getting-started/vpn-access.md
    - System Usage Policies: getting-started/system-usage-policies.md
    - Data Retention Policies: getting-started/data-retention-policies.md
    - Best Practices for Supercomputer Users: getting-started/best-practices-for-supercomputer-users.md
    - Acknowledging NCAR and CISL: getting-started/acknowledging-ncar-and-cisl.md

  - Getting Help:
    - user-support/index.md
#   - Troubleshooting Tips:
#     - Killed processes on login nodes: user-support/troubleshooting-tips/killed-processes-on-login-nodes.md
#     - Common causes of job failures: user-support/troubleshooting-tips/common-causes-of-job-failures.md
#     - Batch jobs crashing: user-support/troubleshooting-tips/batch-job-crashing.md

  - Compute Systems and Services:
    - Derecho:
      - compute-systems/derecho/index.md
      - Derecho Use Policies: compute-systems/derecho/derecho-use-policies.md
      - Compiling Code on Derecho: compute-systems/derecho/compiling-code-on-derecho/index.md
      # - Process Binding : compute-systems/derecho/process-binding.md TODO: FILL PAGE
      - Derecho Software: compute-systems/derecho/derecho-modules.md
      - Moving to Derecho from Cheyenne: compute-systems/derecho/moving-from-cheyenne.md
    - Casper:
      - compute-systems/casper/index.md
      - Casper Use Policies: compute-systems/casper/casper-use-policies.md
      - Casper Node Types: compute-systems/casper/casper-node-types.md
      - Compiling Code on Casper: compute-systems/casper/compiling-code-on-casper/index.md
      - Using Remote Desktops: compute-systems/casper/remote-desktops.md
      - Casper Software: compute-systems/casper/casper-modules.md
    - CIRRUS:
      - compute-systems/cirrus/guides/01-intro/index.md
      - Introduction: compute-systems/cirrus/guides/01-intro/index.md
      - Interact with CIRRUS team:
            - compute-systems/cirrus/guides/02-interact-with-cirrus-team/agile.md
            - compute-systems/cirrus/guides/02-interact-with-cirrus-team/create-tickets.md
      - Deploying Applications: 
            - compute-systems/cirrus/guides/03-deploying-applications/index.md
            - compute-systems/cirrus/guides/03-deploying-applications/containerize.md
            - compute-systems/cirrus/guides/03-deploying-applications/additions.md
            - compute-systems/cirrus/guides/03-deploying-applications/alerts.md
      - Kubernetes API Access: compute-systems/cirrus/guides/10-kubectl/kubectl.md
      - S3 Storage: compute-systems/cirrus/guides/11-storage/s3.md
      - Container Registry:
        - compute-systems/cirrus/guides/04-container-registry/index.md
        - Image Management: compute-systems/cirrus/guides/04-container-registry/image-mgmt.md
        - Vulnerability Scanner: compute-systems/cirrus/guides/04-container-registry/vulnerability-scan.md
      - GitHub Actions:
        - compute-systems/cirrus/guides/05-github-actions/best-practices.md
        - compute-systems/cirrus/guides/05-github-actions/scale-sets.md
      - Jupyter on CIRRUS:
        - compute-systems/cirrus/guides/06-jupyter-on-cirrus/jupyterhub.md
        - Conda Environments: compute-systems/cirrus/guides/06-jupyter-on-cirrus/conda-envs.md
        - GPU Use: compute-systems/cirrus/guides/06-jupyter-on-cirrus/jhub-gpu.md
        - Dask: compute-systems/cirrus/guides/06-jupyter-on-cirrus/jhub-dask.md
        - Binder: compute-systems/cirrus/guides/06-jupyter-on-cirrus/binderhub.md
      - Secret Manager: compute-systems/cirrus/guides/07-secret-manager/openbao.md
      - Frequent Issues: compute-systems/cirrus/guides/08-frequent-issues/index.md
      - Service Level Agreements: compute-systems/cirrus/guides/09-service-level-agreements/slas.md
    - JupyterHub:
      - compute-systems/jupyterhub/index.md
      - Jupyter and IPython: compute-systems/jupyter-and-ipython.md
    - Additional Resources:
      - Cron services: compute-systems/additional-resources/cron.md
      - Thunder test system: compute-systems/additional-resources/thunder-test-system.md

  - Running Jobs (PBS):
      - pbs/index.md
      - Job Scripts:
        - pbs/job-scripts/index.md
        - Derecho Job Script Examples: pbs/job-scripts/derecho-job-script-examples.md
        - Casper job Script Examples: pbs/job-scripts/casper-job-script-examples.md
      - Queues and Charging: pbs/charging.md
      - Job Dependencies: pbs/job-dependencies.md
      - Peer Scheduling between Systems: pbs/peer-scheduling.md
      - Job Preemption with PBS: pbs/preemption.md
      - Common Causes of Job Failures:
        - pbs/common-causes-of-job-failures/index.md
        - Checking Memory Use: pbs/checking-memory-use/index.md
      - Storing temporary files: pbs/storing-temporary-files.md

  - Storage Systems and Data Transfer:
    - storage-systems/index.md
    - GLADE (POSIX File Systems):
      - storage-systems/glade/index.md
      - Campaign storage file system: storage-systems/glade/campaign.md
      - Scratch Lustre file system: storage-systems/glade/lustre.md
      - Setting File and Directory Permissions: storage-systems/glade/setting-file-directory-permissions.md
      - Using Access Control Lists : storage-systems/glade/using-access-control-lists.md
      - Recovering files from snapshots : storage-systems/glade/recovering-files-from-snapshots.md
      - Removing large number of files : storage-systems/glade/removing-large-number-of-files.md
    - Quasar (Tape Storage):
      - storage-systems/quasar/index.md
      - Quasar system specifications : storage-systems/quasar/quasar+system+specifications.md
    - Stratus (Object Storage): storage-systems/stratus/index.md
    - Transferring Data:
      - storage-systems/data-transfer/index.md
      - Globus:
         - storage-systems/data-transfer/globus/index.md
         - Sharing data and making unattended transfers: storage-systems/data-transfer/globus/Sharing+data+and+making+unattended+transfers.md
      - SSH based tools: storage-systems/data-transfer/scp-and-sftp.md
    - CMIP Analysis Platform: storage-systems/cmip-analysis-platform.md

  - User Environment:
    - environment-and-software/user-environment/index.md
    - Using Modules: environment-and-software/user-environment/modules.md
    - Customizing your Environment: environment-and-software/user-environment/customizing.md
    - Environment & Package Managers:
      - Conda: environment-and-software/user-environment/package-managers/conda.md
      - Pixi: environment-and-software/user-environment/package-managers/pixi.md
      - uv: environment-and-software/user-environment/package-managers/uv.md
      - Spack: environment-and-software/user-environment/package-managers/spack/spack.md
    - Containers:
      - environment-and-software/user-environment/containers/index.md
      - Working with Containers: environment-and-software/user-environment/containers/working_with_containers.md
      - Example Workflows: environment-and-software/user-environment/containers/examples.md

  - HPC Software:
    - environment-and-software/hpc-software/index.md
    - Community Models: 
        - Available Models: environment-and-software/community-models.md
        - Compiling WRF: environment-and-software/wrf_on_derecho.md
        - Compiling WRF-Chem: environment-and-software/wrfchem_on_derecho.md
    - Data Analysis and Visualization : environment-and-software/data-analysis-and-visualization.md
    - NCL : environment-and-software/ncl.md
    - MATLAB Parallel Computing Toolbox: environment-and-software/matlab-parallel-computing-toolbox.md
    - Numerical Libraries: environment-and-software/numerical-libraries.md
    - Machine Learning and Deep Learning : environment-and-software/machine-learning-and-deep-learning.md
    - NCAR Classic Libraries for Geophysics: environment-and-software/ncar-classic-libraries-for-geophysics.md
    - Utilities: environment-and-software/user-environment/utilities.md
    - VS Code: environment-and-software/vscode.md
    - Profiling & Debuggers: # -- tentative placement
      - Debugging and Profiling with Forge Tools: environment-and-software/hpc-software/profiling-and-debuggers/running-ddt-map-and-pr-jobs.md
      - Intel Parallel Studio XE: environment-and-software/hpc-software/profiling-and-debuggers/intel-parallel-studio-xe.md
    - Benchmarks:
      - environment-and-software/benchmarks/index.md
      - NCAR Benchmarking applications - 2015 release: environment-and-software/benchmarks/ncar-benchmarking-2015.md
      - NCAR Benchmarking applications - 2019-2020 release: environment-and-software/benchmarks/ncar-benchmarking-2019-2020.md

  - Tutorials:
    - tutorials/index.md
    - New User Training: tutorials/new-user-training.md
    - Derecho Overview: tutorials/derecho-overview.md
    - Dask Tutorial: tutorials/dask-tutorial.md
    - Profiling and Debugging: tutorials/profiling-and-debugging.md
    - Managing Permissions and Data Sharing: tutorials/permissions-and-data-sharing.md
    - Using Globus v5: tutorials/globus.md
    - NCAR Storage Spaces: tutorials/storage.md
    - JupyterHub:  tutorials/jupyterhub.md
    - Remote Desktop Services: tutorials/remote-desktops.md
#    - Containers: tutorials/containers.md
#    - GPU Workshop: tutorials/gpu-workshop.md

  - NCAR User Group (NHUG):
    - nhug/index.md

  - Contributing to the Documentation:
    - contributing/index.md

# ------------------------------------
# -- configuration - themes
# (note theme.yml should be a symbolic link to one of several options'
# ------------------------------------
INHERIT: theme.yml

extra_javascript:
  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML

copyright: '&copy; 2023-2026 UCAR, Licensed under the <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons CC-BY-SA 4.0</a>.'

# ------------------------------------
# -- configuration - extensions
# ------------------------------------
markdown_extensions:
  - meta
  - attr_list
  - footnotes
  - admonition
  - md_in_html
  - def_list
  - toc:
      permalink: true
      title: "Page Outline"

  # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
     url_download: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - codehilite:
      guess_lang: true

  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols:
      fractions: false
  - pymdownx.superfences
  - pymdownx.details
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.keys
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: squidfunk
      repo: mkdocs-material
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# ------------------------------------
# -- configuration - extensions
# ------------------------------------
plugins:
  - search:
      enabled: true
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom
      slide_effect: slide
      width: 100%
      height: auto
      zoomable: true
      draggable: true
      skip_classes:
        - custom-skip-class-name
      auto_caption: false
      caption_position: bottom
  - macros
  - minify:
      minify_html: true
  - open-in-new-tab
  - mkdocs-jupyter:
      include_source: true
      ignore_h1_titles: true
  - redirects:
      redirect_maps:
        'nhug/index.md': 'https://nhug.readthedocs.io/en/latest/'
        # CIRRUS redirects - OLD paths -> NEW numbered guide paths
        # This will be removed before 01/01/2026 and does not need to be maintained
        'compute-systems/cirrus/index.md': 'compute-systems/cirrus/guides/01-intro/index.md'
        'compute-systems/cirrus/users/agile.md': 'compute-systems/cirrus/guides/02-interact-with-cirrus-team/agile.md'
        'compute-systems/cirrus/users/create-tickets.md': 'compute-systems/cirrus/guides/02-interact-with-cirrus-team/create-tickets.md'
        'compute-systems/cirrus/users/hosting/containerize.md': 'compute-systems/cirrus/guides/03-deploying-applications/containerize.md'
        'compute-systems/cirrus/users/hosting/additions.md': 'compute-systems/cirrus/guides/03-deploying-applications/additions.md'
        'compute-systems/cirrus/users/container-registry/index.md': 'compute-systems/cirrus/guides/04-container-registry/index.md'
        'compute-systems/cirrus/users/container-registry/image-mgmt.md': 'compute-systems/cirrus/guides/04-container-registry/image-mgmt.md'
        'compute-systems/cirrus/users/container-registry/vulnerability-scan.md': 'compute-systems/cirrus/guides/04-container-registry/vulnerability-scan.md'
        'compute-systems/cirrus/users/github/best-practices.md': 'compute-systems/cirrus/guides/05-github-actions/best-practices.md'
        'compute-systems/cirrus/users/github/scale-sets.md': 'compute-systems/cirrus/guides/05-github-actions/scale-sets.md'
        'compute-systems/cirrus/users/jupyter/jupyterhub.md': 'compute-systems/cirrus/guides/06-jupyter-on-cirrus/jupyterhub.md'
        'compute-systems/cirrus/users/jupyter/conda-envs.md': 'compute-systems/cirrus/guides/06-jupyter-on-cirrus/conda-envs.md'
        'compute-systems/cirrus/users/jupyter/jhub-gpu.md': 'compute-systems/cirrus/guides/06-jupyter-on-cirrus/jhub-gpu.md'
        'compute-systems/cirrus/users/jupyter/jhub-dask.md': 'compute-systems/cirrus/guides/06-jupyter-on-cirrus/jhub-dask.md'
        'compute-systems/cirrus/users/jupyter/binderhub.md': 'compute-systems/cirrus/guides/06-jupyter-on-cirrus/binderhub.md'
        'compute-systems/cirrus/users/openbao/openbao.md': 'compute-systems/cirrus/guides/07-secret-manager/openbao.md'
        'compute-systems/cirrus/slas.md': 'compute-systems/cirrus/guides/09-service-level-agreements/slas.md'

# ------------------------------------
# -- configuration - extras
# ------------------------------------
extra:
  next_chap_deadline: March 4th 2026
  next_nsc_deadline: mid March 2026
  analytics:
    provider: google
    property: G-RZLJ37D0K6
  social:
    - icon: material/home-circle
      link: https://arc.ucar.edu/
    - icon: material/help-circle
      link: https://ithelp.ucar.edu/plugins/servlet/desk/site/rc
    - icon: fontawesome/brands/github
      link: https://github.com/NCAR
    - icon: fontawesome/brands/slack
      link: https://join.slack.com/t/ncarhpcusergroup/shared_invite/zt-1z00napom-SU0X8CzJWVY90C2GzRvUCg