An extension of the MkDocs Material Theme for ASF
Project description
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 yourmkdocs.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.
-
You can change site logo with a direct link to an image
theme: name: asf-theme logo: images/my-logo.png
-
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_asf_theme-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d001ddb9992e63547fc73ad26d26cc02340a9a6bfee3aed09cdb4572d4f12211 |
|
MD5 | 5f81d58dea5819bc5dc7da61a4428c39 |
|
BLAKE2b-256 | edbf613e200bc5e4f17faefe1490da95b6af3356f2ec7152c1d6a0115b9b8f94 |