statix/mkdocs.yml at main · GeiserX/statix · 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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
site_name: StatiX
site_url: https://geiserx.github.io/statix/
site_description: An R Shiny dashboard that graphs an ISP's PPPoE sessions, upstream traffic and HotSpot users from FreeRADIUS, SNMP and the MikroTik RouterOS API.
repo_url: https://github.com/GeiserX/statix
repo_name: GeiserX/statix
edit_uri: edit/main/docs/

# A warning is a broken link, a missing page or a page nobody can reach. All of
# them fail the build, locally and in CI, so nobody has to remember --strict.
strict: true

theme:
  name: material
  language: en  # The app's labels are Spanish; the docs are English, like the README.
  logo: images/logo.svg
  favicon: images/icon.svg
  # Dark first: the first palette entry is the default, and the banner is dark.
  palette:
    - scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
    - scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - content.code.copy
    - content.action.edit
    - search.highlight
    - search.suggest
    - toc.follow
  icon:
    repo: fontawesome/brands/github

# MkDocs reports most link problems as `info`, which --strict ignores. Every
# line here promotes one of them to a warning so the build fails on it:
#   nav.omitted_files   a Markdown file under docs/ that is in no nav entry and
#                       not in exclude_docs (a page nobody can reach, published
#                       at a public URL anyway);
#   nav.not_found       a nav entry whose file does not exist;
#   links.not_found     a relative link to a page or file that does not exist;
#   links.anchors       a link to a heading that does not exist;
#   links.absolute_links  a link written as /path/ (breaks under the /statix/
#                       prefix of the site);
#   links.unrecognized_links  a relative link that leaves docs/ (../README.md).
#                       Repo files are linked by absolute GitHub URL instead.
validation:
  nav:
    omitted_files: warn
    not_found: warn
    absolute_links: warn
  links:
    not_found: warn
    anchors: warn
    absolute_links: warn
    unrecognized_links: warn

plugins:
  - search
  # No page has been renamed since the site exists, so there is nothing to
  # redirect. When one is, add `mkdocs-redirects==1.2.2` to
  # docs/requirements-docs.txt and uncomment:
  # - redirects:
  #     redirect_maps:
  #       old-name.md: new-name.md

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  # base_path includes the repository root, so a page can include a file that
  # ships word for word with `--8<-- "AtStartupWEB.sh"`. A copied example
  # drifts from the real file; an included one cannot. check_paths makes a
  # missing include fail the build instead of rendering an empty block. No
  # page includes a file today; the day one does, add that file to the push
  # paths of docs.yml.
  - pymdownx.snippets:
      base_path:
        - .
        - docs
      check_paths: true
  - pymdownx.mark
  - attr_list
  - md_in_html
  # Renders :material-xxx: shortcodes as icons. The grid cards on index.md use
  # them; without this they print as literal text.
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - tables
  - toc:
      permalink: true

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/GeiserX/statix

extra_css:
  - stylesheets/theme.css

# Files under docs/ that are not pages. MkDocs publishes every Markdown file in
# docs/ whether or not it is in the nav, so anything that is not a page must be
# listed here. A page is a lowercase kebab-case .md file; anything with a
# capital letter (ROADMAP.md, CHANGELOG.md) is a repo-facing note, and
# design/, research/ and notes/ hold material read on GitHub.
exclude_docs: |
  [A-Z]*.md
  design/
  research/
  notes/
  requirements-docs.txt

# Three tabs, each a section. The nav title equals the page's H1 (index.md is
# the one exception: H1 is the product name, nav title is Home).
nav:
  - Home: index.md
  - Get started:
      - Getting started: getting-started.md
      - Usage: usage.md
  - Reference:
      - Configuration: configuration.md
      - How it works: how-it-works.md
      - Troubleshooting: troubleshooting.md