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
143
144
145
146
147
# The docs site, https://geiserx.github.io/tailscale-rs/, built by .github/workflows/docs.yml.
# Pages are the lowercase .md files in docs/; capitalised files there are notes and stay unpublished.
site_name: tailscale-rs
site_url: https://geiserx.github.io/tailscale-rs/
site_description: A work-in-progress Tailscale library written in Rust. Embed a Tailscale node in your app, with bindings to C, Elixir and Python.
repo_url: https://github.com/GeiserX/tailscale-rs
repo_name: GeiserX/tailscale-rs
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 # es for a Spanish repo: it changes the UI strings, not the content.
logo: images/logo.svg
favicon: images/icon.svg
# Dark first: the first palette entry is the default, and the banners are 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 /tailscale-rs/
# 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
# When a page is renamed (installation.md -> getting-started.md), keep the old URL alive:
# add `mkdocs-redirects==1.2.2` to docs/requirements-docs.txt and uncomment.
# - redirects:
# redirect_maps:
# installation.md: getting-started.md
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
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 (docker-compose.yml, .env.example) word for word with
# `--8<-- "docker-compose.yml"`. 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.
- 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:
emoji_generator:
- tables
- toc:
permalink: true
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/GeiserX/tailscale-rs
- icon: fontawesome/brands/rust
link: https://crates.io/crates/geiserx_tailscale
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. The patterns follow the docs/ contract: a page is a lowercase
# kebab-case .md file; anything with a capital letter (ROADMAP.md, CHANGELOG.md,
# GOAL.md, DESIGN.md) is a repo-facing note, and design/, research/ and notes/
# hold material read on GitHub. Add a line for any other per-repo note.
exclude_docs: |
[A-Z]*.md
design/
research/
notes/
requirements-docs.txt
restock-beads.json
# One entry per canonical page, in the contract's order. Delete the lines for
# pages the repo does not have. A repo-specific page goes after the canonical
# one it extends (a `Metrics` page after Usage, a `Security` page after
# Configuration). The nav title must equal the page's H1.
nav:
- Home: index.md
- Get started:
- Getting started: getting-started.md
- Caveats, versioning and platform support: caveats.md
- Reference:
- How it works: how-it-works.md
- Status: status.md