Skip to main content

An extension of the MkDocs Material Theme for ASF

Project description

ASF MkDocs Theme

PyPI license PyPI pyversions PyPI version

DOI

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_asf_theme-0.4.0.tar.gz (58.9 kB view details)

Uploaded Source

Built Distribution

mkdocs_asf_theme-0.4.0-py3-none-any.whl (51.8 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs_asf_theme-0.4.0.tar.gz.

File metadata

  • Download URL: mkdocs_asf_theme-0.4.0.tar.gz
  • Upload date:
  • Size: 58.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.0 CPython/3.12.4

File hashes

Hashes for mkdocs_asf_theme-0.4.0.tar.gz
Algorithm Hash digest
SHA256 2b067e6adad573bdf5b3e090be0a7d518616100e6f91fb783bae7516309a4c59
MD5 ac6f24c0e7a5fb6382c417b6af800278
BLAKE2b-256 0688ceebf96e716f45c0fa023ce10e782dd11012830fc19a7d5c4f4b88438034

See more details on using hashes here.

File details

Details for the file mkdocs_asf_theme-0.4.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_asf_theme-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d001ddb9992e63547fc73ad26d26cc02340a9a6bfee3aed09cdb4572d4f12211
MD5 5f81d58dea5819bc5dc7da61a4428c39
BLAKE2b-256 edbf613e200bc5e4f17faefe1490da95b6af3356f2ec7152c1d6a0115b9b8f94

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page