ASF MkDocs Theme

An extension of the MkDocs Material Theme for ASF.

Quickstart

This theme is distributed on PyPI and can be installed into a Python 3.10+ environment using pip:

python -m pip install mkdocs-asf-theme

To use this theme, add the following lines to your mkdocs.yml:

theme:
  name: asf-theme

To see an example of using this theme, see ASF HyP3's MkDocs repository which generates ASF HyP3's documentation.

Customization

[!WARNING] You should NOT include the navigation.instant feature in your mkdocs.yml. See https://github.com/ASFHyP3/hyp3-docs/pull/371 for more information.

This theme has been developed with sensible defaults to be used out-of-the-box by ASF documentation sites. While sections below describe how to customize the ASF-specific features of this theme, we hope most users won't need them.

Because this theme is an extension of the MkDocs Material Theme, advanced customization can be done by following the MkDocs Material Theme documentation. However, please consider either:

• opening an issue and requesting any customization you need to be incorporated into this theme
• Opening a pull request to this theme with your customizations so they are available to all ASF documentation sites

Analytics

You can follow https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/ to enable analytics for your site.

Logos

This theme will provide both the ASF logo and a site logo.

ASF logo

You can change the ASF logo and/or logo URL with

theme:
  name: asf-theme
  asf_logo: images/asf-altenate-logo.png
  asf_logo_url: https://asf.alaska.edu/

or remove the ASF logo with

theme:
  name: asf-theme
  asf_logo:

Site logo

With the Material Theme, there are two ways to change the site logo.

1. You can change site logo with a direct link to an image

   theme:
     name: asf-theme
     logo: images/my-logo.png
   

2. or by specifying an icon

   theme:
     name: asf-theme
     icon:
       logo: material/library
   

To remove the site logo, specify an empty icon (and no theme logo)

theme:
  name: asf-theme
  icon:
    logo:

Copyright notice

This theme will provide a copyright notice like

© [YEAR] Alaska Satellite Facility

where [YEAR] is replaced with the current year. You can customize the text after © [YEAR] in your mkdocs.yml with

copyright: Alaska Satellite Facility

To turn off the copyright notice entirely, remove the site level copyright configuration and clear the theme one with

theme:
  name: asf-theme
  copyright:

Social links

You can add additional social links with

extra:
  social:
    - icon: fontawesome/brands/gitter
      link: https://gitter.im/ASFHyP3/community

You can override the theme provided social links with

theme:
  name: asf-theme
  social:
    - icon: fontawesome/brands/gitter
      link: https://gitter.im/ASFHyP3/community

Development

Upgrading mkdocs-material to a new major version

When upgrading the mkdocs-material dependency to a new major version, you should reference the upgrade guide for any important changes.

In particular, you should update each template .html file in asf_theme/partials to match the latest upstream version as closely as possible. Each template file should include a comment near the top of the file with a link to the upstream version upon which it was based. When updating a particular template file, you can diff it against the linked upstream version to see what changes were made. Then you can apply those changes to the latest upstream version of the file.

For example, when updating header.html from major version 9 to 10, you can diff our version of header.html against the 9.x.x upstream version linked near the top of the file. Then you can download the latest 10.x.x upstream version from https://github.com/squidfunk/mkdocs-material and apply the diff changes, adapting them as necessary for the latest version of mkdocs-material.

You may also have to update asf_theme/assets/stylesheets/asf.css, asf_theme/partials/main.html, and asf_theme/mkdocs_theme.yml as appropriate.