UTL/mkdocs.yml at master · DmitriBogdanov/UTL · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
# __________________________________ CONTENTS ___________________________________
#
#    This is a MkDocs Material config for automatically deployed GitHub Pages,
#    see https://squidfunk.github.io/mkdocs-material/
# _______________________________________________________________________________

# ============
# --- Core ---
# ============

site_name: "UTL"

site_url: https://dmitribogdanov.github.io/UTL/

repo_url: https://github.com/DmitriBogdanov/UTL

repo_name: DmitriBogdanov/UTL

# ===========================
# --- Markdown extensions ---
# ===========================

# We need 3 extensions:
#    1. Github-flavor callouts
#    2. LaTeX
#    3. Code blocks nested in block quotes
#
# Default 'admonition' plugin uses a different syntax so it's not suitable for callouts.
# Thankfully, we can still achieve it with 3rd party plugins.
#
# [install 3rd party plugins]: 'pip install markdown-callouts'

markdown_extensions:
  - github-callouts      # enables Github-flavour callouts
  - pymdownx.arithmatex: # enables KaTeX parser
      generic: true      #
  - pymdownx.superfences # enables nesting of code and content blocks
  - toc:                 # enables permalink buttons next to the section headings
      permalink: true    #

extra_javascript:
  - mkdocs/mathjax.js                                # standard Mathjax includes
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js #
  - mkdocs/modification/header_title.js              # sets header title separately from site name
  - mkdocs/modification/relative_links.js            # adjusts relative links to work with the website

# =========================
# --- Style & structure ---
# =========================

# [install 3rd party plugins]: 'pip install mkdocs-awesome-nav'

plugins:
  - offline     # enables HTML with relative paths
  - search      # enables search function
  - social      # enables thumbnail generation for externally shared links
  - awesome-nav # enables navigation hierarchy specified by '.nav.yml' rather than directory structure

theme:
  name: material

  favicon: images/icon_site_logo.ico

  icon:
    logo: material/tools
    repo: fontawesome/brands/github

  # Color palette with a light/dark mode toggle
  palette:
    # Dark mode (default)
    - scheme: slate
      toggle:
        icon: material/toggle-switch-off
        name: Switch to light mode
      primary: black
      accent: light blue
    # Light mode
    - scheme: default
      toggle:
        icon: material/toggle-switch
        name: Switch to dark mode
      primary: deep purple
      accent: purple

  features:
    - toc.follow        # makes the sidebar automatically scroll to keep current TOC heading visible
    - content.code.copy # adds copy button to code blocks
    - search.suggest    # adds greyed-out suggestion to the search
    - content.tooltips  # improves the style of hover tooltips (library name, permalink button, mode switch, repo link)
    # - navigation.instant          # dispatches internal links without refresh (makes loading feel smoother)
    # - navigation.instant.progress # shows loading bar if page load takes over 400ms

# [! Warning !]: Instant navigation changes all relative 'href' links, which breaks current link replacement rules.
#                Since it also prevents page reload tracking & replacing links going outside the website (aka to repo)
#                becomes significantly more difficult.

# Footer configuration
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/DmitriBogdanov

copyright: "Copyright &copy; 2023–2025 Dmitri Bogdanov"


extra_css:
  - mkdocs/callouts.css # fix for 'markdown-callouts' plugin missing the style for '[!Important]'
  - mkdocs/width.css    # makes page content wide on large screens