Package: mkdocs-asf-theme
ASF MkDocs ThemeAn extension of theMkDocs Material Themefor ASF.QuickstartThis theme is distributed onPyPIand can be installed into a Python 3.8+ environment usingpip:python -m pip install mkdocs-asf-themeTo use this theme, add the following lines to yourmkdocs.yml:theme:name:asf-themeTo see an example of using this theme, seeASF HyP3's MkDocs repositorywhich generatesASF HyP3's documentation.Customization[!WARNING]
You should NOT include thenavigation.instantfeature in yourmkdocs.yml.
Seehttps://github.com/ASFHyP3/hyp3-docs/pull/371for 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 theMkDocs Material Theme,
advanced customization can be done by following the MkDocs Material Themedocumentation.However, please
consider either:opening an issueand requesting any customization you need to be incorporated into this themeOpening a pull request to this theme with your customizations so they are available
to all ASF documentation sitesAnalyticsYou can followhttps://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/to enable analytics for your site.LogosThis theme will provide both the ASF logo and a site logo.ASF logoYou can change the ASF logo and/or logo URL withtheme:name:asf-themeasf_logo:images/asf-altenate-logo.pngasf_logo_url:https://asf.alaska.edu/or remove the ASF logo withtheme:name:asf-themeasf_logo:Site logoWith the Material Theme, there aretwo ways to change the site logo.You can change site logo with a direct link to an imagetheme:name:asf-themelogo:images/my-logo.pngor by specifying an icontheme:name:asf-themeicon:logo:material/libraryTo remove the site logo, specify an empty icon (and no theme logo)theme:name:asf-themeicon:logo:Copyright noticeThis theme will provide a copyright notice like© [YEAR] Alaska Satellite Facilitywhere[YEAR]is replaced with the current year. You can customize the text after© [YEAR]in yourmkdocs.ymlwithcopyright:Alaska Satellite FacilityTo turn off the copyright notice entirely, remove the site levelcopyrightconfiguration and clear the theme one withtheme:name:asf-themecopyright:Social linksYou can addadditionalsocial links withextra:social:-icon:fontawesome/brands/gitterlink:https://gitter.im/ASFHyP3/communityYou canoverridethe theme provided social links withtheme:name:asf-themesocial:-icon:fontawesome/brands/gitterlink:https://gitter.im/ASFHyP3/communityDevelopmentUpgradingmkdocs-materialto a new major versionWhen upgrading themkdocs-materialdependency to a new major version,
you should reference theupgrade guidefor any important changes.In particular, you should update each template.htmlfile inasf_theme/partialsto 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 candiffit against the linked upstream version to see what changes were made.
Then you can apply those changes to thelatestupstream version of the file.For example, when updatingheader.htmlfrom major version 9 to 10,
you candiffour version ofheader.htmlagainst the9.x.xupstream version linked near the top of the file.
Then you can download the latest10.x.xupstream version fromhttps://github.com/squidfunk/mkdocs-materialand apply thediffchanges, adapting them as necessary for the latest version ofmkdocs-material.You may also have to updateasf_theme/assets/stylesheets/asf.css,asf_theme/partials/main.html,
andasf_theme/mkdocs_theme.ymlas appropriate.